FileShare/deploy

文件快传 部署编排（deploy/）

Go 1.27.1（Gin + GORM）+ Vue 3 重写版（v3.1）的容器化部署。数据库默认 SQLite，零外部依赖 （modernc.org/sqlite 纯 Go 驱动，无需 Postgres），可选切换 Postgres（--profile postgres）； Redis 为可选增强（--profile redis），未配置 FCB_REDIS_ADDR 时服务端自动降级为进程内存缓存。

v3.1 功能提示：管理后台可设「站点对外域名」（内网部署生成公网分享链接）、 分享时支持自定义提取码（4-8 位字母数字）；这些均为运行时配置，无需改部署。

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，也无需任何数据库环境变量：

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/filecodebox.db（WAL 模式，父目录自动创建）。
• .env 中 Postgres 段变量（POSTGRES_USER/PASSWORD/DB）在此模式下不生效，无需修改。

路径 ②：Postgres 模式（可选）

1. 编辑 .env：

   FCB_DB_DRIVER=postgres
   FCB_DB_DSN=postgres://filecodebox:filecodebox@postgres:5432/filecodebox?sslmode=disable
   

2. 带 postgres profile 启动（server 会等 postgres 健康检查通过后再启动）：

   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 启动：

# S3 引擎（MinIO 冒烟）
docker compose --profile minio up -d --build   # .env: FCB_STORAGE_ENGINE=s3
#   minio-init 一次性任务自动建桶（mc mb filecodebox）

# WebDAV 引擎（dufs 冒烟，Basic 认证 admin/admin123@/:rw）
docker compose --profile webdav up -d --build  # .env: FCB_STORAGE_ENGINE=webdav

v3 起支持运行时热切换：也可不改 .env，直接在管理后台「系统设置 → 存储引擎」 三选并保存引擎参数后点切换（健康检查通过才生效，失败保持原引擎），或调用 POST /admin/storage/switch——均无需重启容器。.env 的 FCB_STORAGE_ENGINE 仅作为首次启动（KV 为空时）的默认引擎。

Redis 缓存增强（可选）

Redis 不是必需服务：--profile redis 启动且 .env 设 FCB_REDIS_ADDR=redis:6379 才接入； 未配置（或未启用该 profile）时服务端自动降级为进程内存缓存，单实例部署功能完全可用， 多实例部署或需要重启保活计数/会话场景时建议启用。

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：

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（filecodebox/filecodebox）默认凭据仅限本机冒烟；对外部署必须修改， 且不建议把 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。