46 lines
2.9 KiB
Markdown
46 lines
2.9 KiB
Markdown
# 本地后端 Docker Compose
|
||
|
||
Compose 当前只启动 WebDrop API。前端继续使用现有的开发/独立托管方式；本地 Vite 开发服务器通过 `/api/v1` 代理访问 `127.0.0.1:5000`。API 默认只绑定 loopback，SQLite 数据保存在项目的 `./data` 目录。
|
||
|
||
## 启动
|
||
|
||
```powershell
|
||
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`。删除该目录会永久删除这些数据。
|
||
|
||
## 前端连接
|
||
|
||
本机 `npm run dev` 使用 Vite 代理连接默认 API。独立部署前端时，在前端托管层把 `/api/v1` 代理到此 API 地址，这样无需开放 CORS。也可以为跨域托管配置 `WebDrop__CorsOrigins`，值应为明确的前端源列表。
|
||
|
||
公网部署时，在 API 前配置 HTTPS 反向代理，并让代理连接 API 的 loopback 端口。不要把未加密 HTTP 直接暴露到公网。只有当该 API 端口仅能由可信代理访问时，才将 `WEBDROP_TRUST_FORWARDED_HEADERS` 设为 `true`。
|
||
|
||
## 验证码
|
||
|
||
默认 `CAPTCHA_PROVIDER=none`。启用 Cap 时，在 `.env` 设置：
|
||
|
||
```dotenv
|
||
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 契约、Core、Web、服务端检查，并解析后端 Compose 配置。每次更新都会构建前端。`.woodpecker/release-backend.yml` 仅响应 `vMAJOR.MINOR.PATCH` SemVer tag；测试通过后构建并推送同名后端镜像 tag。
|
||
|
||
后端镜像发布到 `zot.oeo.one/justme/webdrop-api`。在 Woodpecker 仓库配置 tag 事件可用的 secrets `registry_username`、`registry_password`。Docker Buildx 发布步骤以特权模式运行；Woodpecker Agent 必须将仓库设为 security trusted，并把 `woodpeckerci/plugin-docker-buildx:5.0.0` 加入服务端的 `WOODPECKER_PLUGINS_PRIVILEGED`。使用已发布镜像时，在 `.env` 中设置 `WEBDROP_IMAGE_TAG`；仓库名已填入 `.env.example`。
|
||
|
||
API 契约版本以 `contracts/api-contract.json` 为准，并同步到 OpenAPI 与后端 `/api/v1/info`。加字段等向后兼容更新递增 minor，兼容性修复递增 patch，破坏性更新递增 major。前端声明支持的契约主版本；后端主版本变化时，前端 CI 契约检查和运行时连接检查都会失败，直到前端同步支持该主版本。
|
||
|
||
## 数据备份
|
||
|
||
停止服务或使用一致性快照后备份 `./data`。目录里保存 SQLite 元数据和服务端收到的帧字节；加密频道/分享的内容帧是密文。备份仍需按敏感数据保护，因为 raw 频道按设计保存明文负载。
|