feat(docs): add source deployment maintenance guide - #179
Conversation
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
There was a problem hiding this comment.
本次审阅覆盖新增维护手册及其入口链接，并对照当前源码部署脚本、systemd 单元和生产 Compose 配置核对了保留资源、配置变更、自动部署与回滚流程。以下两处会让维护操作产生与文档相反的结果，建议合并前修正。
Additional findings
docs/source-deployment-maintenance.md:?: [P1] Do not restart the auto-sync service for rollback: 这条回滚流程在git reset --hard <GOOD_SHA>后启动unispeaking-source-deploy.service，但该 service 会运行sync-build-deploy.sh，先git fetch --prune origin main，再把工作区重置到最新的origin/main。所以只要<GOOD_SHA>不是当前main，服务会立即覆盖回滚结果并部署坏版本，维护人员无法按此步骤恢复。请改为在固定提交上显式构建/启动 Compose，或为部署脚本增加不会重新同步的回滚路径，并在验收后再恢复 timer。
| 同步脚本执行 `git reset --hard` 和 `git clean` 时会保留： | ||
|
|
||
| - `/opt/unispeaking/deploy/env/`，包括生产 `.env` 和环境备份； | ||
| - `/opt/unispeaking/backups/`，包括数据库和代码备份； |
There was a problem hiding this comment.
[P1] Ensure deployment preserves the documented backups
文档把 /opt/unispeaking/backups/ 列为同步时必须保留的资源，但 sync-build-deploy.sh 实际执行的 git clean -fd -e deploy/env/ -e runtime-logs/ -e .source-deploy-state 没有排除 backups/；因此下一次源码部署会删除其中的未跟踪数据库/代码备份。更具体地说，前面的配置变更示例还把 .env 备份写入这个目录，随后该备份会在部署时丢失。请让脚本和文档使用同一保留规则（或改用脚本已经保留的目录），并补上目录创建/验证步骤。
| 同步脚本执行 `git reset --hard` 和 `git clean` 时会保留： | ||
|
|
||
| - `/opt/unispeaking/deploy/env/`，包括生产 `.env` 和环境备份； | ||
| - `/opt/unispeaking/backups/`，包括数据库和代码备份； |
There was a problem hiding this comment.
[P1] Ensure deployment preserves the documented backups
文档把 /opt/unispeaking/backups/ 列为同步时必须保留的资源，但 sync-build-deploy.sh 实际执行的 git clean -fd -e deploy/env/ -e runtime-logs/ -e .source-deploy-state 没有排除 backups/；因此下一次源码部署会删除其中的未跟踪数据库/代码备份。更具体地说，前面的配置变更示例还把 .env 备份写入这个目录，随后该备份会在部署时丢失。请让脚本和文档使用同一保留规则（或改用脚本已经保留的目录），并补上目录创建/验证步骤。
| git log --oneline -20 | ||
| git reset --hard <GOOD_SHA> | ||
| git clean -fd -e deploy/env/ -e backups/ -e runtime-logs/ -e .source-deploy-state | ||
| systemctl start --no-block unispeaking-source-deploy.service |
There was a problem hiding this comment.
[P1] Do not restart the auto-sync service for rollback
这条回滚流程在 git reset --hard <GOOD_SHA> 后启动 unispeaking-source-deploy.service，但该 service 会运行 sync-build-deploy.sh，先 git fetch --prune origin main，再把工作区重置到最新的 origin/main。所以只要 <GOOD_SHA> 不是当前 main，服务会立即覆盖回滚结果并部署坏版本，维护人员无法按此步骤恢复。请改为在固定提交上显式构建/启动 Compose，或为部署脚本增加不会重新同步的回滚路径，并在验收后再恢复 timer。
2 participants
变更说明
新增源码部署维护手册，方便后续开发和运维人员维护生产部署。
文档内容
/opt/unispeaking工作区及服务器持久化资源说明.env、第三方密钥和前端 VITE 配置修改流程影响范围