From 909a016a448f6a4288f60fd3212f0f8c87ca5df6 Mon Sep 17 00:00:00 2001 From: loveuer Date: Sun, 18 Jan 2026 17:52:39 +0800 Subject: [PATCH] docs: add comprehensive README - Add project introduction and features - Add quick start guide (development and production) - Add configuration documentation - Add usage instructions - Add mobile support section - Add development guide and directory structure --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..496bc5f --- /dev/null +++ b/README.md @@ -0,0 +1,168 @@ +# UShare + +一个简单易用的文件分享工具，支持大文件分片上传下载，以及局域网内 P2P 文件分享。 + +## 功能特性 + +- 📁 大文件分片上传下载 +- 🌐 网页端文件分享 +- 🏠 局域网 P2P 文件分享（WebRTC） +- 📱 响应式设计，支持移动端 +- 🔐 简单的用户认证 +- 🚀 单一二进制，开箱即用 +- 🐳 Docker 支持 + +## 快速开始 + +### 开发模式 + +```bash +# 克隆仓库 +git clone https://github.com/loveuer/ushare.git +cd ushare + +# 启动开发服务器 +./dev.sh +``` + +开发服务器会同时启动后端（http://0.0.0.0:9119）和前端（http://0.0.0.0:5173），前端支持热重载。 + +### 生产模式 + +#### 使用预编译二进制 + +从 [Releases](https://github.com/loveuer/ushare/releases) 下载对应平台的二进制文件。 + +```bash +# Linux amd64 +wget https://github.com/loveuer/ushare/releases/download/v0.3.2/ushare-linux-amd64 +chmod +x ushare-linux-amd64 + +# 运行 +./ushare-linux-amd64 -data ./data +``` + +#### 从源码构建 + +```bash +# 构建单一二进制（包含嵌入的前端） +./make.sh + +# 运行 +./dist/ushare -data ./data +``` + +#### Docker 部署 + +```bash +docker build -t ushare:latest . +docker run -d -p 80:80 -v $(pwd)/data:/data ushare:latest +``` + +## 配置 + +### 命令行参数 + +```bash +ushare [options] + +Options: + -debug 启用调试模式 + -address string 监听地址 (default "0.0.0.0:9119") + -data string 数据目录 (default "/data") + -clean int 文件清理周期，单位：小时，0 表示不自动清理 (default 24) +``` + +### 环境变量 + +| 环境变量 | 说明 | 默认值 | +|---------|------|--------| +| `USHARE_USERNAME` | 用户名 | `admin` | +| `USHARE_PASSWORD` | 密码 | `ushare@123` | + +#### 示例 + +```bash +# 使用默认凭据（admin / ushare@123） +./ushare -data ./data + +# 使用自定义凭据 +export USHARE_USERNAME=myuser +export USHARE_PASSWORD=mypass +./ushare -data ./data +``` + +## 使用说明 + +### 文件分享 + +1. 访问 http://localhost:9119/share +2. 点击"选择文件"选择要上传的文件 +3. 点击"上传文件"，等待上传完成 +4. 复制生成的下载码分享给他人 + +### 文件下载 + +1. 访问 http://localhost:9119/share +2. 在"获取文件"区域输入下载码 +3. 点击"获取文件"下载文件 + +### 局域网 P2P 分享 + +1. 访问 http://localhost:9119 +2. 自动注册到局域网设备列表 +3. 选择要分享的设备，建立 P2P 连接 +4. 开始文件传输 + +## 移动端支持 + +- 响应式设计，自动适配手机、平板等设备 +- 移动端（≤768px）采用垂直布局，优化触摸操作 +- 按钮尺寸优化，适合手指点击 + +## 开发 + +### 目录结构 + +``` +ushare/ +├── internal/ # 后端代码 +│ ├── api/ # HTTP API 路由 +│ ├── controller/ # 业务逻辑 +│ ├── handler/ # 请求处理器 +│ ├── model/ # 数据模型 +│ ├── opt/ # 配置管理 +│ └── pkg/ # 工具包 +├── frontend/ # 前端代码 +│ └── src/ +│ ├── api/ # API 调用 +│ ├── component/ # UI 组件 +│ ├── hook/ # 自定义 Hooks +│ ├── page/ # 页面组件 +│ └── store/ # 状态管理 +├── .github/workflows/ # GitHub Actions +├── dist/ # 构建输出（.gitignore） +└── data/ # 数据目录（.gitignore） +``` + +### 构建 + +```bash +# 开发构建（前后端分离） +./dev.sh + +# 生产构建（单一二进制） +./make.sh +``` + +### 代码风格 + +请参考 [AGENTS.md](./AGENTS.md) 了解代码风格指南。 + +## License + +MIT License + +## 贡献 + +欢迎提交 Issue 和 Pull Request！