4.5 KiB
本地后端 Docker Compose
Compose 当前只启动一个 WebDrop API 容器；构建镜像时会先构建 web/，再由独立的 WebDrop.Frontend 模块将静态资源嵌入后端。访问 http://127.0.0.1:5000/ 打开前端，API 使用同源 /api/v1。API 默认只绑定 loopback，SQLite 数据保存在项目的 ./data 目录。
启动
Copy-Item .env.example .env
docker compose config
docker compose up -d --build
docker compose ps
API 地址为 http://127.0.0.1:5000。停止服务使用 docker compose down；数据库和服务器存储的帧会保留在 ./data。删除该目录会永久删除这些数据。
前端连接
本机开发仍可使用 cd web; npm run dev，Vite 会代理 /api/v1 到本地 API。独立托管前端时，可单独构建 web/ 并在前端托管层反向代理 /api/v1；跨域直连则配置明确的 WebDrop__CorsOrigins。
公网部署时，在 API 前配置 HTTPS 反向代理，并让代理连接 API 的 loopback 端口。不要把未加密 HTTP 直接暴露到公网。只有当该 API 端口仅能由可信代理访问时，才将 WEBDROP_TRUST_FORWARDED_HEADERS 设为 true。
嵌入模式减少自托管组件，但前端代码与 API 来自同一个部署信任域。若要让 API 节点被攻破时仍不能替换前端，应使用独立域名托管前端。
验证码
默认 CAPTCHA_PROVIDER=none。启用 Cap 时，在 .env 设置：
CAPTCHA_PROVIDER=cap
CAPTCHA_API_ENDPOINT=https://captcha.example.com/<site-key>/
CAPTCHA_SITEVERIFY_URL=https://captcha.example.com/<site-key>/siteverify
CAPTCHA_SECRET=<server-side-secret>
CAPTCHA_API_ENDPOINT 会提供给浏览器；CAPTCHA_SITEVERIFY_URL 和 CAPTCHA_SECRET 仅供 API 容器使用。不要提交 .env。
Woodpecker CI
.woodpecker/ci.yml 在默认分支 push、pull request 和手动运行时执行 API 契约与服务端检查；.woodpecker/web-build.yml 同时执行 Core 测试向量、类型检查、Web CSS lint、测试和构建。两个 workflow 独立运行，让前后端验证并行。默认分支当前为 master，配置也兼容迁移后的 main。
默认分支每次 push 和 PR 都会跑常规检查。提交信息含 [SKIP TESTS] 时只跳过服务端测试；API 契约检查和前端/Core 检查照常运行。提交信息含 [CI] 时，.woodpecker/dev-image.yml 会等 ci 和 web-build 都通过后，构建并推送带提交 SHA 的开发镜像以及可变 dev 标签。开发镜像不会覆盖 release tag 或 latest。发布目标为 registry.oeo.one/justme/webdrop-api；Buildah 使用 Woodpecker secret registry_api_key 作为 Zot API key 的密码字段，用户名为 justme，并启用默认 TLS 校验。Gitea clone 凭据保存在 gitea_clone_webdrop secret。
.woodpecker/release-backend.yml 响应 vMAJOR.MINOR.PATCH SemVer tag；也可手动运行并传入 RELEASE_TAG(例如 v0.1.0)。发布 workflow 会重新执行 Core、Web 和服务端完整检查，全部通过后才用 Linux native agent 的 Buildah 构建并推送后端镜像 tag 与 latest。所有 workflow 都通过 Woodpecker secret gitea_clone_webdrop 从 https://git.oeo.one 克隆公开仓库。
两条流水线固定到 ci: domain-linux-native 的 linux/amd64 Agent；该主机需要 Node 24、.NET 10 和 Buildah。release job 在 WOODPECKER_BACKEND_LOCAL_TEMP_DIR 对应的持久目录缓存 Buildah 层，Dockerfile 单独缓存 NuGet restore 层。Gitea webhook 走同 Docker 网络中的 woodpecker-server:8000，代码 clone 走公网 Git 域名。
后端镜像发布到 registry.oeo.one/justme/webdrop-api。Woodpecker Linux agent 通过 TLS 连接 registry；发布需要 Buildah 与 push/tag/manual 事件可用的 registry_api_key secret。使用已发布镜像时，在 .env 中设置 WEBDROP_IMAGE_TAG，仓库名已填入 .env.example。
API 契约版本以 contracts/api-contract.json 为准，并同步到 OpenAPI 与后端 /api/v1/info。加字段等向后兼容更新递增 minor，兼容性修复递增 patch，破坏性更新递增 major。前端声明支持的契约主版本；后端主版本变化时，前端 CI 契约检查和运行时连接检查都会失败，直到前端同步支持该主版本。
数据备份
停止服务或使用一致性快照后备份 ./data。目录里保存 SQLite 元数据和服务端收到的帧字节；加密频道/分享的内容帧是密文。备份仍需按敏感数据保护，因为 raw 频道按设计保存明文负载。