SKYMirror
84df9996cb
CI 测试 / go vet + go test (push) Successful in 49s
- 全项目版本号统一：v3.x 迭代号（26.9/26.9/26.9/26.9 及裸 v2/v3）→ 26.9， 覆盖 Go 注释 / 文档 / openapi.yaml / README×4 / 前端源码（80+ 处） - v31_test.go 更名 custom_code_test.go；TestV2AccessorDefaults → TestKVAccessorDefaults - docs/api/00-overview.md 更新日志合并为单条 26.9 条目（修复错位拼接） - .goreleaser.yaml 头部注释与实际一致（Pro 2.18.1 / GITEA_TOKEN / semver tag 要求） - CI：release-image.yml → ci.yml，仅保留 vet+test 门禁； 镜像发布移交 GoReleaser Pro（原 build-push 的 tag 校验与 26.9 版本方案冲突，历史 9 次失败） - 前端重建：server/web/dist 与 web-embed 同步（docs 文案嵌入更新）
138 lines
7.2 KiB
Markdown
138 lines
7.2 KiB
Markdown
# 文件快传 部署编排（deploy/）
|
||
|
||
Go 1.27.1（Gin + GORM）+ Vue 3 重写版（26.9）的容器化部署。数据库**默认 SQLite，零外部依赖**
|
||
（modernc.org/sqlite 纯 Go 驱动，无需 Postgres），可选切换 Postgres（`--profile postgres`）；
|
||
Redis 为可选增强（`--profile redis`），未配置 `FCB_REDIS_ADDR` 时服务端自动降级为进程内存缓存。
|
||
|
||
> 26.9 功能提示：管理后台可设「站点对外域名」（内网部署生成公网分享链接）、
|
||
> 分享时支持自定义提取码（4-8 位字母数字）；这些均为运行时配置，无需改部署。
|
||
> 26.9 新增：管理后台可设「上行/下行带宽」限速（字节/秒，0=不限速），立即生效。
|
||
> S3 预签名直传（客户端→S3）服务端无法介入限速，其余下载/上传路径均覆盖。详见《[带宽限速](../docs/api/13-bandwidth.md)》。
|
||
|
||
## compose 服务与 profile 一览
|
||
|
||
| 启动方式 | 服务 | 说明 |
|
||
|---|---|---|
|
||
| `docker compose up -d --build` | server | **默认：SQLite 零依赖**，仅启动一个容器 |
|
||
| `--profile postgres` | postgres | 可选：Postgres 数据库（数据落 `pgdata` 卷） |
|
||
| `--profile redis` | redis | 可选：缓存增强（未配置自动内存降级） |
|
||
| `--profile minio` | minio + minio-init | 可选：S3 引擎冒烟（minio-init 用 mc 自动建桶） |
|
||
| `--profile webdav` | webdav | 可选：WebDAV 引擎冒烟（dufs） |
|
||
|
||
## 数据库双路径（需求 ⑧）
|
||
|
||
### 路径 ①：默认 SQLite（零依赖，推荐）
|
||
|
||
无需 postgres profile，也无需任何数据库环境变量：
|
||
|
||
```bash
|
||
cd deploy
|
||
cp .env.example .env # 保持 FCB_DB_DRIVER=sqlite、FCB_DB_DSN 留空（默认值即可）
|
||
docker compose up -d --build
|
||
# 打开 http://localhost:8466（.env 可用 WEB_PORT 改端口）→ 自动跳转 /setup 完成初始化
|
||
```
|
||
|
||
- 数据落 **`serverdata` 卷**：容器内 `/app/data/fileshare.db`（WAL 模式，父目录自动创建）。
|
||
- `.env` 中 Postgres 段变量（`POSTGRES_USER/PASSWORD/DB`）在此模式下不生效，无需修改。
|
||
|
||
### 路径 ②：Postgres 模式（可选）
|
||
|
||
1. 编辑 `.env`：
|
||
|
||
```dotenv
|
||
FCB_DB_DRIVER=postgres
|
||
FCB_DB_DSN=postgres://fileshare:fileshare@postgres:5432/fileshare?sslmode=disable
|
||
```
|
||
|
||
2. 带 postgres profile 启动（server 会等 postgres 健康检查通过后再启动）：
|
||
|
||
```bash
|
||
docker compose --profile postgres up -d --build
|
||
```
|
||
|
||
- compose 将 `.env` 的 `FCB_DB_DRIVER/FCB_DB_DSN` 透传给 server 容器；DSN 主机必须为 compose
|
||
服务名 `postgres`，凭据与 `POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB` 一致。
|
||
- Postgres 数据落 `pgdata` 卷；首次启动自动执行迁移（AutoMigrate）。
|
||
|
||
> 注意：设置 `FCB_DB_DRIVER=postgres` 后务必带 `--profile postgres` 启动，否则 postgres
|
||
> 服务不会创建，server 将因连不上数据库而反复重启。
|
||
|
||
服务未初始化时（两种数据库模式行为一致）除 `/setup` 与 `/api/v1/health` 外一律返回 428，
|
||
浏览器打开站点按向导设置管理员密码。
|
||
|
||
## 存储引擎切换（本地 / S3 / WebDAV）
|
||
|
||
修改 `.env` 中 `FCB_STORAGE_ENGINE` 并带对应 profile 启动：
|
||
|
||
```bash
|
||
# S3 引擎（MinIO 冒烟）
|
||
docker compose --profile minio up -d --build # .env: FCB_STORAGE_ENGINE=s3
|
||
# minio-init 一次性任务自动建桶（mc mb fileshare）
|
||
|
||
# WebDAV 引擎（dufs 冒烟，Basic 认证 admin/admin123@/:rw）
|
||
docker compose --profile webdav up -d --build # .env: FCB_STORAGE_ENGINE=webdav
|
||
```
|
||
|
||
> **26.9 起支持运行时热切换**：也可不改 `.env`，直接在管理后台「系统设置 → 存储引擎」
|
||
> 三选并保存引擎参数后点切换（健康检查通过才生效，失败保持原引擎），或调用
|
||
> `POST /admin/storage/switch`——均无需重启容器。`.env` 的 `FCB_STORAGE_ENGINE`
|
||
> 仅作为首次启动（KV 为空时）的默认引擎。
|
||
|
||
## Redis 缓存增强（可选）
|
||
|
||
Redis 不是必需服务：`--profile redis` 启动**且** `.env` 设 `FCB_REDIS_ADDR=redis:6379` 才接入；
|
||
未配置（或未启用该 profile）时服务端**自动降级为进程内存缓存**，单实例部署功能完全可用，
|
||
多实例部署或需要重启保活计数/会话场景时建议启用。
|
||
|
||
```bash
|
||
docker compose --profile redis up -d --build # .env: FCB_REDIS_ADDR=redis:6379
|
||
```
|
||
|
||
## 文件说明
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `Dockerfile` | 三阶段构建：node 构建 web/dist → go 编译（go:embed 前端产物）→ alpine 运行镜像 |
|
||
| `docker-compose.yml` | server + 四个可选 profile：postgres / redis / minio（含 mc 建桶）/ webdav |
|
||
| `.env.example` | 全量环境变量：`FCB_DB_DRIVER` 双路径、三引擎切换、`WEB_PORT`、可信代理 |
|
||
|
||
## 健康检查与验证
|
||
|
||
端口由 `.env` 的 `WEB_PORT`（默认 `8466`）映射到容器内 `8466`：
|
||
|
||
```bash
|
||
curl http://localhost:8466/api/v1/health # {"code":200,"data":{"status":"ok",...}}
|
||
curl -I http://localhost:8466/ # 200，前端 SPA
|
||
curl -I http://localhost:8466/docs # 200（SPA 回退）
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- **数据持久化**：SQLite 数据库与本地引擎文件都在 `serverdata` 卷（容器内 `/app/data`）；
|
||
Postgres 模式数据在 `pgdata` 卷；redis/minio/webdav 数据各在独立卷。
|
||
切换数据库驱动不会自动迁移既有数据（SQLite 文件与 Postgres 库互相独立）。
|
||
- **非 root 运行**：容器以 uid 10001 运行。
|
||
- **日志**：`docker compose logs -f server`。
|
||
- **CORS**：同源部署无需额外配置；`/admin/*` 已收紧——仅同源或 `site_domain` 白名单可跨域调用，
|
||
其余跨域由浏览器拦截；公开接口维持 `*`（Bearer 认证，无 Cookie CSRF 面）。
|
||
|
||
## 安全清单（生产部署必读）
|
||
|
||
安全审计（`docs/security-audit-2026-09-05.md`）后的部署要求：
|
||
|
||
1. **反向代理必须配置可信代理**：`.env` 设 `FCB_TRUSTED_PROXIES=<代理IP/CIDR>`（逗号分隔）。
|
||
否则限流按代理 IP 计数（全体用户共享一个限流桶、互相误伤），审计日志 IP 失真；
|
||
也不可把不受信地址加进来——那会允许伪造 `X-Forwarded-For` 绕过限流。
|
||
2. **部署后立即初始化管理员**：打开站点完成 `/setup`（设置 ≥8 位密码），
|
||
或在 `.env` 设 `FCB_ADMIN_PASSWORD`（≥8 位）让服务启动即自动初始化，
|
||
消除「公网上被抢先访问 /setup 接管」的窗口。初始化完成后建议从 `.env` 移除该变量。
|
||
3. **修改组件默认凭据**：minio（`minioadmin/minioadmin`）、webdav（`admin/admin123`）、
|
||
Postgres（`fileshare/fileshare`）默认凭据仅限本机冒烟；对外部署必须修改，
|
||
且不建议把 9000/9001/5005 端口发布到公网（compose 中删除对应 `ports` 或仅绑 127.0.0.1）。
|
||
4. **Postgres 建议启用 TLS**：默认示例 DSN 为 `sslmode=disable`，生产请改为
|
||
`sslmode=require` 及以上。
|
||
5. **管理员会话默认 7 天**（可在管理端调 1~365 天）；修改管理员密码会使全部旧 token 失效。
|
||
6. **上传/登录限流**依赖内存或 Redis 缓存；Redis 故障时自动降级为进程内限流（单实例语义）。
|
||
7. **后台清理任务**：服务内置每 10 分钟的过期容量预留 / 超时上传会话 / 直传残留对象清理，
|
||
无需额外 cron。
|