Update README.md

Author: zy84338719

.github/README.md

@@ -1,188 +1,223 @@
-# GitHub Actions 工作流程
+# FileCodeBox · Go Edition
 
-本项目包含了完整的 CI/CD 工作流程，用于自动化构建、测试和发布。
+> 一个专为自托管场景打造的高性能文件 / 文本分享平台，提供安全、可扩展、可插拔的“随手分享”体验。
 
-## 工作流程概览
+---
 
-### 1. CI (持续集成) - `.github/workflows/ci.yml`
+## 📌 项目概览
 
-**触发条件：**
-- 推送到 `main` 或 `develop` 分支
-- 创建 Pull Request
+FileCodeBox 是一个使用 Go 实现的轻量级分享服务，核心目标是“部署简单、使用顺手、运营安心”。无论你想在团队内搭建一个文件投递站，还是希望为个人项目提供临时分享通道，都可以通过它快速上线并稳定运行。
 
-**功能：**
-- 多版本 Go 测试 (1.20, 1.21)
-- 代码质量检查 (golangci-lint)
-- 安全扫描 (gosec)
-- 测试覆盖率报告
+### 你可以用它做什么？
 
-### 2. Build and Release - `.github/workflows/build.yml`
+- 📁 **拖拽上传**，生成短链接后分享文件或文本片段
+- 🔐 **后台管理**，集中查看、搜索、统计、审核、删除分享内容
+- 🪶 **多存储后端**，根据需求切换本地/对象存储/WebDAV/OneDrive 等方案
+- ⚙️ **自定义配置**，调整限速、过期策略、主题皮肤，让系统和业务完美贴合
 
-**触发条件：**
-- 推送标签 (v*.*.*)
-- 推送到 main 分支
-- Pull Request
+---
 
-**功能：**
-- **多平台构建：**
-  - Linux (amd64, arm64)
-  - macOS (amd64, arm64) 
-  - Windows (amd64, arm64)
-- **Docker 镜像构建**
-- **自动发布：** 标签推送时自动创建 GitHub Release
+## 🌟 关键特性
 
-### 3. Deploy - `.github/workflows/deploy.yml`
+| 分类 | 能力速览 |
+| --- | --- |
+| 性能 | Go 原生并发、分片上传、断点续传、秒传校验 |
+| 分享体验 | 文本 / 文件双通道、链接有效期控制、密码和访问次数限制 |
+| 管理后台 | 仪表板、文件列表、用户管理、存储面板、系统配置、维护工具 |
+| 安全 | 初始化向导、动态路由热载、JWT 管理登录、限流中间件、可选用户体系 |
+| 存储 | 本地磁盘、S3 兼容对象存储、WebDAV、OneDrive（均可扩展） |
+| 部署 | Docker / Docker Compose、systemd、Nginx 反代、跨平台二进制 |
+| 前端 | 主题系统（`themes/2025`）、自适应布局、可自定义静态资源 |
 
-**触发条件：**
-- 发布新版本
-- 手动触发
+---
 
-**功能：**
-- Docker 镜像发布到 Docker Hub
-- Docker 镜像发布到 GitHub Container Registry
+## 🧩 架构速写
 
-## 使用指南
+```
+┌───────────────────────────────────────────────────────────┐
+│                           Client                           │
+│  Web UI (themes) · 管理后台 · RESTful API · CLI · WebDAV   │
+└───────────────▲───────────────────────────────▲───────────┘
+                │                               │
+        Admin Console                     Public Sharing
+                │                               │
+┌──────────────┴───────────────────────────────┴─────────────┐
+│                       FileCodeBox Server                    │
+│                                                             │
+│  Routes  ─ internal/routes           Middleware             │
+│  Handlers ─ internal/handlers        RateLimit · Auth       │
+│  Services ─ internal/services        Chunk · Share · User   │
+│  Repos    ─ internal/repository      GORM Data Access       │
+│  Config   ─ internal/config          动态配置管理           │
+└──────────────┬───────────────────────────────┬─────────────┘
+               │                               │
+       Storage Manager                 Database (SQLite/MySQL/PG)
+          └─ local / S3 / WebDAV / OneDrive · 可插拔
+```
 
-### 🏗️ 日常开发
+初始化流程已经内置了“未初始化只允许访问 `/setup`”的安全护栏：
 
-1. **推送代码** 到 `main` 或 `develop` 分支会触发 CI 流程
-2. **创建 PR** 会运行完整的测试套件
-3. **推送到 main** 会额外触发构建流程
+1. 首次运行 → 自动跳转至 Setup 向导创建数据库 + 管理员
+2. 一旦初始化成功 → 所有用户请求 `/setup` 会被重定向至首页，同时拒绝重复初始化
 
-### 📦 发布新版本
+---
+
+## 🚀 快速起步
 
-1. **创建标签：**
-   ```bash
-   git tag -a v1.0.0 -m "Release version 1.0.0"
-   git push origin v1.0.0
-   ```
+### 1. 环境要求
 
-2. **自动执行：**
-   - ✅ 构建多平台可执行文件
-   - ✅ 构建 Docker 镜像
-   - ✅ 创建 GitHub Release
-   - ✅ 上传构建产物
+- **Go** 1.21 及以上（开发环境推荐 1.24+）
+- **SQLite / MySQL / PostgreSQL**（三选一，默认 SQLite）
+- 可选：Docker 20+、docker-compose v2、Make、Git
 
-### 🐳 Docker 镜像
+### 2. 本地开发
 
-**公开镜像：**
 ```bash
-# Docker Hub
-docker pull filecodebox/filecodebox:latest
-docker pull filecodebox/filecodebox:v1.0.0
+# 拉取依赖
+go mod tidy
 
-# GitHub Container Registry  
-docker pull ghcr.io/zy84338719/filecodebox:latest
+# 运行服务
+go run ./...
+# 或编译后运行
+make build && ./bin/filecodebox
 ```
 
-### 📋 配置要求
+服务默认监听 `http://127.0.0.1:12345`。首次访问会被引导到 `/setup` 完成初始化。
 
-为了完整使用所有功能，需要在 GitHub 仓库中配置以下 Secrets：
+### 3. Docker / Compose
 
-#### 必需的 Secrets
+```bash
+# Docker
+docker build -t filecodebox .
+docker run -d \
+  --name filecodebox \
+  -p 12345:12345 \
+  -v $(pwd)/data:/data \
+  filecodebox
+
+# docker-compose
+cp docker-compose.yml docker-compose.override.yml   # 如需自定义
+docker-compose up -d
+```
 
-| Secret Name | 描述 | 用途 |
-|-------------|------|------|
-| `DOCKER_USERNAME` | Docker Hub 用户名 | 发布 Docker 镜像 |
-| `DOCKER_PASSWORD` | Docker Hub 密码/Token | 发布 Docker 镜像 |
+**生产环境建议**：
 
-#### 可选的 Secrets
+- 使用 `docker-compose.prod.yml` + `.env` 管理数据库凭证
+- 通过 Nginx/Traefik 等反向代理启用 HTTPS 与缓存策略
+- 将 `data/`、数据库与对象存储做持久化与定期备份
 
-| Secret Name | 描述 | 用途 |
-|-------------|------|------|
-| `CODECOV_TOKEN` | Codecov Token | 上传测试覆盖率 |
+### 4. CLI 管理
 
-### 🔧 自定义构建
+```bash
+./filecodebox admin user list
+./filecodebox admin stats
+```
 
-#### 修改构建平台
+所有 CLI 子命令定义在 `internal/cli`，适合在自动化运维或脚本中使用。
 
-编辑 `.github/workflows/build.yml` 中的 `matrix` 部分：
+---
 
-```yaml
-strategy:
-  matrix:
-    include:
-      - goos: linux
-        goarch: amd64
-        output: filecodebox-linux-amd64
-      # 添加或删除平台...
-```
+## 🛠️ 配置指南
 
-#### 修改 Docker 配置
+所有配置均由 `config.yml` + 数据库动态配置组合而成：
 
-编辑 `Dockerfile` 和相关工作流程文件。
+| 配置域 | 说明 |
+| --- | --- |
+| `base` | 服务端口、站点名称、DataPath |
+| `storage` | 存储类型、凭证、路径 |
+| `transfer` | 上传限额、断点续传、分片策略 |
+| `user` | 用户系统开关、配额、注册策略 |
+| `mcp` | 消息通道 / WebSocket 服务配置 |
+| `ui` | 主题、背景、页面说明文案 |
 
-#### 自定义发布说明
+初始化完成后，配置会同步写入数据库并可在后台在线修改。每次操作都走事务保证一致性。
 
-修改 `.github/workflows/build.yml` 中的 `Generate release notes` 步骤。
+> **提示**：未初始化时，仅开放 `/setup`、部分静态资源与 `GET /user/system-info`，避免系统在部署初期被误用。
 
-## 构建产物
+---
 
-### 可执行文件
+## 🧑‍💻 管理后台一览
 
-每次发布会生成以下文件：
+- **仪表盘**：吞吐趋势、存储占用、系统告警
+- **文件管理**：模糊搜索、批量操作、访问日志
+- **用户管理**：启用用户系统、分配配额、状态冻结
+- **存储配置**：即时切换存储后端，并对接健康检查
+- **系统配置**：修改站点基础信息、主题、分享策略
+- **维护工具**：清理过期数据、生成导出、查看审计日志
 
-- `filecodebox-linux-amd64.tar.gz`
-- `filecodebox-linux-arm64.tar.gz`  
-- `filecodebox-darwin-amd64.tar.gz`
-- `filecodebox-darwin-arm64.tar.gz`
-- `filecodebox-windows-amd64.zip`
-- `filecodebox-windows-arm64.zip`
+访问入口：`/admin/`，登录采用 JWT + Bearer Token。自 2025 版起，所有 `admin` 静态资源均由后台鉴权动态下发，避免公共缓存泄露。
 
-### Docker 镜像
+---
 
-- 支持 `linux/amd64` 和 `linux/arm64` 架构
-- 多标签发布：`latest`, `v1.0.0`, `v1.0`, `v1`
+## 📦 存储与上传
 
-## 版本信息
+| 类型 | 说明 |
+| --- | --- |
+| `local` | 默认方案，数据持久化在 `data/uploads` |
+| `s3` | 兼容 S3 的对象存储（如 MinIO、阿里云 OSS） |
+| `webdav` | 适合挂载 NAS / Nextcloud |
+| `onedrive` | 利用 Microsoft Graph 的云端存储 |
 
-构建的可执行文件包含版本信息：
+上传采用“分片 + 秒传 + 断点续传”的三段式策略：
 
-```bash
-./filecodebox -version
-```
+1. `POST /chunk/upload/init/` 初始化会返回 upload_id
+2. 并行调用 `POST /chunk/upload/chunk/:id/:idx`
+3. 最后 `POST /chunk/upload/complete/:id` 合并并校验
 
-输出示例：
-```
-FileCodeBox v1.0.0
-Commit: a1b2c3d4e5f6...
-Built: 2024-01-01T12:00:00Z
-Go Version: go1.21+
-```
+上传状态可通过 `GET /chunk/upload/status/:id` 观察，也可主动 `DELETE /chunk/upload/cancel/:id` 终止。
+
+---
+
+## 📚 API 与 SDK
+
+虽然 FileCodeBox 主要针对 Web 场景，但服务本身围绕 REST API 架构，便于集成：
+
+| 模块 | 典型接口 |
+| --- | --- |
+| 分享 | `POST /share/text/` · `POST /share/file/` · `GET /share/select/?code=...` |
+| 分片 | `POST /chunk/upload/init/` · `POST /chunk/upload/complete/:id` |
+| 用户 | `POST /user/login` · `POST /user/register`（启用用户系统时） |
+| 管理 | `GET /admin/stats` · `POST /admin/files/delete` 等 |
+| 健康检查 | `GET /health` |
+
+API 文档位于 `docs/swagger-enhanced.yaml`，可通过 `go install github.com/swaggo/swag/cmd/swag@latest` 生成最新文档。
 
-## 故障排除
+---
+
+## 🧑‍🔬 本地开发与贡献
+
+1. Fork & clone 仓库
+2. `make dev`（或参考 `Makefile`）
+3. 运行测试：`go test ./...`
+4. 提交前确保通过 `golangci-lint`/`go fmt`（在 CI 中亦会执行）
+
+项目保持模块化、接口清晰，欢迎贡献以下方向：
 
-### 常见问题
+- 新的存储适配器 / 用户登录方式
+- 管理后台的交互优化与国际化支持
+- 自动化部署脚本（Helm / Terraform）
+- 更丰富的 API 客户端（Python/Node/Swift）
 
-1. **Docker 推送失败**
-   - 检查 `DOCKER_USERNAME` 和 `DOCKER_PASSWORD` 是否正确配置
-   - 确认 Docker Hub 仓库权限
+提交 PR 时请附上：变更说明、测试方式、潜在影响。如涉及迁移，请编写相应文档放在 `docs/`。
 
-2. **构建失败**
-   - 检查 Go 版本兼容性
-   - 查看构建日志中的具体错误信息
+---
+
+## 🗺️ 路线图（节选）
 
-3. **测试失败**
-   - 确保所有依赖都在 `go.mod` 中正确声明
-   - 检查代码质量问题
+- [ ] Webhook / EventHook（上传完成、分享到期、超额告警）
+- [ ] 更细颗粒度的访问控制（到期提醒、下载密码、白名单）
+- [ ] 多节点部署指南（对象存储 + Redis + MySQL）
+- [ ] 管理后台模块化主题系统 & 深色主题
+- [ ] CLI 支持导入/导出配置模板
 
-### 调试技巧
+欢迎在 Issues 区讨论新需求或报告缺陷。
+
+---
 
-1. **查看工作流日志：** GitHub Actions 标签页
-2. **本地测试：** 
-   ```bash
-   # 运行测试
-   go test ./...
-   
-   # 代码检查
-   golangci-lint run
-   
-   # 构建测试
-   go build -v ./...
-   ```
+## 📄 许可证
 
-3. **手动触发：** 在 Actions 标签页可以手动触发部署工作流
+MIT License  © FileCodeBox Contributors
 
 ---
 
-更多信息请参考 [GitHub Actions 文档](https://docs.github.com/en/actions)。
+> 💬 有任何问题、部署疑问或定制需求，欢迎通过 Issue / Discussions / 邮件联系。我们乐于协助每一个想把 FileCodeBox 搭建成“团队内部效率神器”的你。