diff --git a/docs/EXECUTION_docker-only-cleanup.zh-CN.md b/docs/EXECUTION_docker-only-cleanup.zh-CN.md new file mode 100644 index 0000000..1a08ba8 --- /dev/null +++ b/docs/EXECUTION_docker-only-cleanup.zh-CN.md @@ -0,0 +1,116 @@ +# Docker-only 清理执行拆解(提交粒度与顺序) + +日期:2026-02-28 +范围:仅“部署体系统一到 Docker-only”的清理;不引入 Caddy,不改 WebRTC 传输护栏。 +提交要求:每个子任务一个 **英文** commit message(`git commit -m "..."`)。 + +## 总目标 + +- 删除裸机部署体系相关代码/文档/脚本(不兼容、不保留、不归档)。 +- 将仓库所有“部署入口”统一为 Docker 一键部署:`deploy.sh` + `docker compose`。 +- 同步更新 README 与 AI Playbook,确保不存在指向被删除文件的链接或描述。 + +## 提交拆解(建议顺序) + +> 原则:每个 commit 在语义上自洽;尽量避免“文档指向不存在文件”的中间状态。 + +### Commit 1:统一对外入口(先断开裸机入口) + +**Commit message(English)**: +- `docs: make Docker the only supported deployment path` + +**修改内容**: +- 更新 `README.md`:移除裸机部署指南入口,部署方式只保留 Docker。 +- 更新 `README.zh-CN.md`:同上。 +- 更新 `docs/ai-playbook/index.md`:移除裸机部署指南链接,只保留 Docker 部署链接。 +- 更新 `docs/ai-playbook/index.zh-CN.md`:同上。 + +**验收点**: +- README/Playbook 索引不再出现 `docs/DEPLOYMENT.md` / `docs/DEPLOYMENT.zh-CN.md`。 + +--- + +### Commit 2:更新 Playbook 代码地图(移除裸机相关入口文件) + +**Commit message(English)**: +- `docs(playbook): remove bare-metal deployment entries` + +**修改内容**: +- 更新 `docs/ai-playbook/code-map.md` +- 更新 `docs/ai-playbook/code-map.zh-CN.md` + +**重点**: +- 移除或调整对 `ecosystem.config.js`、`build-and-deploy.sh`、`deploy.config.example` 的描述。 +- 仅保留 Docker-only 主线入口:`deploy.sh`、`docker-compose.yml`、`docker/scripts/*`。 + +--- + +### Commit 3:更新架构文档中对 PM2/裸机部署文件的引用(避免删文件后文档失真) + +**Commit message(English)**: +- `docs: remove PM2/bare-metal references` + +**修改内容(视实际引用范围)**: +- `docs/BACKEND_ARCHITECTURE.md` +- `docs/BACKEND_ARCHITECTURE.zh-CN.md` +- 以及任何仍引用 `ecosystem.config.js` / PM2 / 裸机 Nginx 的文档条目 + +--- + +### Commit 4:删除裸机部署指南文档 + +**Commit message(English)**: +- `chore: remove bare-metal deployment guides` + +**删除内容**: +- `docs/DEPLOYMENT.md` +- `docs/DEPLOYMENT.zh-CN.md` + +--- + +### Commit 5:删除裸机运维资产(backend/docker) + +**Commit message(English)**: +- `chore: remove bare-metal ops assets under backend/docker` + +**删除内容**: +- `backend/docker/`(整个目录) + +--- + +### Commit 6:删除 PM2/远程发布链路 + +**Commit message(English)**: +- `chore: remove PM2-based deploy scripts` + +**删除内容**: +- `ecosystem.config.js` +- `build-and-deploy.sh` +- `deploy.config.example` + +--- + +### Commit 7:收尾校验与文档一致性(可选但推荐) + +**Commit message(English)**: +- `docs: align deployment references after cleanup` + +**内容**: +- 全仓 `rg` 检查是否仍出现: + - `DEPLOYMENT.md` / `DEPLOYMENT.zh-CN.md` + - `ecosystem.config.js` + - `build-and-deploy.sh` + - `deploy.config` + - `backend/docker/` +- 修复剩余引用(若存在)。 + +## 验证建议(在实现阶段执行) + +- `rg -n "DEPLOYMENT\\.md|ecosystem\\.config\\.js|build-and-deploy\\.sh|backend/docker" -S .` +- 前端构建:`cd frontend && pnpm build`(按协作规则要求 `next build` 通过) +- Docker 构建(如环境允许):`docker compose build` + +## 回滚策略 + +- 任何问题:直接 `git revert ` 回滚到清理前状态(删除类变更不做手工回滚)。 + diff --git a/docs/PLAN_docker-only-cleanup.zh-CN.md b/docs/PLAN_docker-only-cleanup.zh-CN.md new file mode 100644 index 0000000..e7e1279 --- /dev/null +++ b/docs/PLAN_docker-only-cleanup.zh-CN.md @@ -0,0 +1,146 @@ +# PrivyDrop 部署体系统一(Docker-only)清理计划(提案,未实施) + +日期:2026-02-28 +状态:提案 / 等待批准(不执行任何删除动作前需再次确认) +讨论结论:**不保留、不兼容、不归档**,所有非 Docker 部署体系相关代码/资源将直接删除。 + +## 背景与问题陈述 + +当前仓库同时存在两条“生产部署”路径,导致入口分散、维护口径漂移、对新人不友好: + +1) **Docker 一键部署(主线候选)** +- 入口脚本:`deploy.sh` +- 编排:`docker-compose.yml` +- 配置生成:`docker/scripts/generate-config.sh`(按模式生成 `.env`、`docker/nginx/*`、`docker/coturn/*`、`docker/ssl/*` 等运行产物) +- 健康/自检:`docker/scripts/test-deployment.sh` +- 文档:`docs/DEPLOYMENT_docker.zh-CN.md` / `docs/DEPLOYMENT_docker.md`、README 中 Docker 部分 + +2) **裸机部署(PM2 + Nginx + Certbot + Coturn + Redis)** +- 文档:`docs/DEPLOYMENT.zh-CN.md` / `docs/DEPLOYMENT.md` +- 裸机依赖安装:`backend/docker/env_install.sh` +- 裸机 Nginx 脚本/模板:`backend/docker/Nginx/*` +- 裸机 TURN 模板:`backend/docker/TURN/*` +- PM2 配置/远程打包发布:`ecosystem.config.js`、`build-and-deploy.sh`、`deploy.config.example` + +“两套部署系统”同时存在的直接后果: +- 文档与脚本互相矛盾(证书、端口、入口、同源网关策略等),难以长期一致。 +- `backend/docker/*` 命名会误导为 Docker 部署的一部分(但实际是裸机运维资产)。 +- 后续要做的「Caddy 替代 Nginx」在 full 模式又涉及 `turns:443` 保留与 443 SNI 分流;若不先清理裸机路径,将放大维护成本。 + +## 本次变更目标(Docker-only 清理) + +Goals +- 仓库对外仅保留**一条**官方部署路径:Docker 一键部署(`deploy.sh` + `docker compose`)。 +- 删除所有裸机部署体系相关的脚本/模板/远程发布工具链,避免继续误导与漂移。 +- 将 README 与 AI Playbook(code-map/flows)中与部署入口相关的描述收敛到 Docker-only。 + +Non-Goals(明确不做) +- 不修改 WebRTC 传输护栏(分片/背压/重试等关键参数不动)。 +- 不变更信令协议、Socket.IO 事件名等对外兼容面。 +- 不在本次 PR 引入 Caddy(仅做“清理统一”;Caddy 迁移另起单一主题 PR)。 + +## 必要前提(来自讨论) + +- 部署形态:`full`(公网域名) +- 必须保留:`turns:443`(受限网络兼容) +- 证书流程:先保持现状(当前 `deploy.sh` + certbot + `docker/ssl/*` + 热重载逻辑) + +## 影响范围(拟删除清单) + +> 说明:下列文件/目录均属于“裸机部署体系”,与 Docker-only 主线目标冲突,按你的要求将直接删除(不保留归档)。 + +### 1) 裸机部署文档 +- `docs/DEPLOYMENT.zh-CN.md` +- `docs/DEPLOYMENT.md` + +理由:与 `docs/DEPLOYMENT_docker*.md` 并列存在会持续制造双入口与口径漂移。 + +### 2) 裸机依赖安装与配置资产(命名含 docker 但非 Docker 主线) +- `backend/docker/`(整个目录) + - `backend/docker/env_install.sh` + - `backend/docker/Nginx/*` + - `backend/docker/TURN/*` + - `backend/docker/Dockerfile` + +理由:与 `docker/scripts/generate-config.sh`、`docker-compose.yml` 的 Docker 一键部署主线无关;目录名会长期误导。 + +### 3) PM2/远程发布链路 +- `ecosystem.config.js` +- `build-and-deploy.sh` +- `deploy.config.example` + +理由:属于裸机发布路径;Docker-only 后应彻底退出主线以避免继续维护。 + +## 需要保留并作为主线的部署资产 + +- `deploy.sh` +- `docker-compose.yml` +- `docker/`(当前仅 `docker/scripts/*` 在仓库中;其余 `docker/nginx`、`docker/ssl`、`docker/coturn` 等为运行时生成目录/产物) +- `docs/DEPLOYMENT_docker.zh-CN.md`、`docs/DEPLOYMENT_docker.md` +- `README.md`、`README.zh-CN.md`(将统一只推荐 Docker) +- `docker/scripts/test-deployment.sh`(作为 Docker-only 自检脚本) + +注:`test-health-apis.sh` 目前更偏“直连端口的开发/调试”,可保留但需在 README 中明确定位,避免被当成生产验收脚本。 + +## 文档同步更新清单(本次必须做) + +由于本次清理会影响“入口文件路径/流程”,需要在同一 PR 内同步更新: +- `README.md`:移除/弱化裸机部署入口,仅保留 Docker 部署主线入口。 +- `README.zh-CN.md`:同上。 +- `docs/ai-playbook/code-map.zh-CN.md`:删除或调整与裸机部署相关的入口与文件列表。 +- `docs/ai-playbook/flows.zh-CN.md`:如包含裸机流程入口或引用,需同步删除/调整。 + +(若英文 playbook 也引用了相关入口:`docs/ai-playbook/code-map.md`、`docs/ai-playbook/flows.md` 同步处理。) + +## 实施步骤(单一主题 PR:Docker-only 清理) + +1) 删除裸机部署文档:`docs/DEPLOYMENT*.md`(非 docker 版本) +2) 删除裸机运维资产:`backend/docker/` +3) 删除 PM2/远程发布链路:`ecosystem.config.js`、`build-and-deploy.sh`、`deploy.config.example` +4) 更新 README(中英)到 Docker-only(并明确 full 模式 + turns:443 的能力边界) +5) 更新 AI Playbook:`docs/ai-playbook/code-map*`、`docs/ai-playbook/flows*` +6) 验证(见下节) + +## 验收标准(Acceptance Criteria) + +- 仓库中不存在裸机部署体系的入口文件(上述删除清单均移除)。 +- 文档入口统一: + - README(中英)只指向 Docker 部署指南与 `deploy.sh`。 + - Playbook 的 code-map/flows 中不再出现被删除文件路径。 +- Docker 部署主线不受影响: + - `bash ./deploy.sh --mode full --domain --with-nginx --with-turn --le-email ` 的说明完整且自洽(本次不改行为,只改入口收敛)。 + +## 验证方式(Validation) + +> 在执行删除后(实现阶段)至少做以下验证;本文件仅定义验证清单,本次提案阶段不执行。 + +- Frontend build:`cd frontend && pnpm install && pnpm build`(要求 next build 通过) +- Docker build:`docker compose build`(full 模式相关 profile 组合) +- Docker smoke test(可选但推荐):`bash docker/scripts/test-deployment.sh` +- 手测回归(最小集): + - 创建/加入房间 + - 双浏览器互传(至少单文件 + 文件夹各一次) + - TURN 连接能力检查:确保 ICE servers 中 `turns::443` 可用(full 场景) + +## 风险与缓解(Risks & Mitigations) + +- 风险:有人仍依赖裸机部署脚本/文档 + - 缓解:在 README 的部署章节明确“已统一到 Docker-only”(并在发布说明/PR 描述中强调破坏性变更) +- 风险:删除 `backend/docker/*` 后,有人误以为 Docker 部署失效 + - 缓解:在 README 和 `docs/DEPLOYMENT_docker*.md` 强调 Docker 主线入口文件清单(`deploy.sh`/`docker-compose.yml`/`docker/scripts/*`) + +## 回滚策略(Rollback) + +由于本次为删除类变更,回滚方式为: +- 使用 Git 回退该 PR(`git revert` 或直接回退分支/提交)。 + +## 后续工作(另起 PR:Caddy 替代 Nginx,保留 turns:443) + +本次只做 Docker-only 清理,不做 Caddy。 + +后续 Caddy 迁移的硬约束(已确认): +- full 模式必须保留 `turns:443` +- 继续沿用现有证书流程(certbot + `docker/ssl/*` + 热更新 hook) + +因此 Caddy 方案需要解决 **443 SNI 分流(turn. → coturn:5349,其余 → web:8443)** 的等价实现(原方案在 Nginx stream 中实现)。这将是单独的设计与实施主题。 +