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
2026-01-18 17:52:39 +08:00
parent 96fe642175
commit 15e30eb787
1 changed files with 168 additions and 0 deletions
--- a/README.md
+++ 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！