主题
十一、部署与运维
本章速览:读完后你会知道 —— ① 生产拓扑、容器与关键挂载(改路径/回环/权限最容易踩坑);② 发布、回滚、迁移、备份与恢复的标准流程;③ 监控、体检(25 项)与常见运维剧本。
生产事实与脚本逐项由
check-deploy-guards.sh与附录 E 校验;本节只补设计意图。
11.1 生产事实
| 项 | 值 |
|---|---|
| 后端容器 | vite-cosmos-app-prod(Compose 项目 vite-cosmos-prod,network_mode: host) |
| 后端进程 | Java 17,JAVA_OPTS=-Xms256m -Xmx896m -XX:SoftMaxHeapSize=512m -XX:+UseG1GC -XX:+ExitOnOutOfMemoryError;容器内以非 root 用户 991(APP_UID=991,所属 www gid 1000)运行 |
| 后端端口 | 8080,实际监听 [::ffff:127.0.0.1]:8080(仅回环,对外由 Nginx 代理) |
| MySQL | 容器 cosmos-mysql,127.0.0.1:3307,库 vite_cosmos,用户 cosmos_app |
| Hindsight | 容器 cosmos-hindsight-hindsight-api-1 / -db-1,经 127.0.0.1:8890 反代(注入 Bearer) |
| 微信桥 | systemd cosmos-wechat-bridge,监听 127.0.0.1:8790 |
| 门户静态 | /www/wwwroot/vite66.cn |
| 文档站 | docs.vite66.cn(宝塔静态站点,VitePress;root /www/wwwroot/docs.vite66.cn,HTTPS) |
| 后台静态 | /www/wwwroot/vite66.cn/admin |
| 上传目录 | 宿主 /opt/vite-cosmos/uploads → 容器 /app/uploads(Nginx 直出) |
| 日志目录 | 宿主 /opt/vite-cosmos/app/logs → 容器 /app/logs |
| 备份目录 | 宿主 /opt/vite-cosmos/backup |
| 容器 bind 挂载 | 共 17 处(业务目录 + 只读 Node.js 运行时 + 只读令牌/日志/会话文件;闸 F 核对其中 8 个关键挂载) |
| 镜像标签 | vite-cosmos-app:prod-<yyyymmdd-HHMMSS>(每次发布新标签,compose 默认标签会被改写) |
容器与宿主机共享目录(2026-11-18 审查 #52 补齐):
/opt/vite-cosmos/uploads(媒体+聊天附件)、/opt/vite-cosmos/app/logs、/opt/vite-cosmos/backup、/opt/vite-cosmos/dsh-upgrade、/opt/vite-cosmos/extension-sandbox/{artifacts,workspaces},以及/opt/vite-cosmos/agent/wechat-bridge/work/admin-chat/chat-cache(后台对话图片物化给桥/DSH)、/opt/vite-cosmos/agent/wechat-bridge/work(只读:微信入站媒体在work/inbox,相册工具从这里取图,审查 #66)、/opt/vite-cosmos/dsh-profiles(DSH web profile 补丁;宿主机/root/.dsh/profiles/web/cordis.patch.yml用 symlink 指到这里,dsh 与后端读写同一份文件)与/opt/vite-cosmos/backup/app(权限改动备份,单独挂可写)、/opt/vite-cosmos/dsh-url.txt与/www/server/panel/plugin/deepseek_harness/logs(DSH RPC 令牌来源, 只读;dsh 重启会换令牌,日志里的最新一条才是有效的 —— 审查 #67)、/opt/vite-cosmos/agent/wechat-bridge/sessions.json(只读:后台切模型时取"当前会话")、/etc/vite-cosmos/agent-mcp-token(后台 AI 对话调桥时的X-Admin-Chat-Token,只读单文件挂载)。 聊天附件根目录从镜像内旧路径迁移到挂载卷是一次性动作:deploy/scripts/migrate-chat-attachments.sh(幂等,源目录保留作归档);doctor.sh会检查"旧目录里的文件是否都已在挂载卷内"(审查 #62)。 缺一个挂载的表现通常是"功能上传/写盘时报 AccessDenied / 令牌不可用",而不是启动失败 —— 所以deploy/scripts/check-deploy-guards.sh的闸 F 会逐个核对这份清单(审查 #52/#54)。
11.2 发布流程
bash
# 1) 后端:构建 jar → 构建镜像 → 起容器 → 等健康检查
./deploy/scripts/deploy-server.sh # 全量构建
./deploy/scripts/deploy-server.sh --no-build # 用已有 jar(会校验 jar 必须新于源码)
# 2) 后台(必须先在前端目录构建)
cd vite-cosmos-admin && npm run build && cd ..
./deploy/scripts/deploy-admin.sh # 要求 .tsc-pass;自动打回滚包
# 3) 门户
cd vite-cosmos-web && npm run build && cd ..
./deploy/scripts/deploy-portal.sh # 含上传资源可访问性断言
# 4) 验证
APP_ENV_FILE=/opt/vite-cosmos/panel/backend.env \
bash deploy/scripts/verify-deploy.sh --host-header vite66.cn # 期望 7/7脚本里的防呆约束(都是踩坑后加的):
| 脚本 | 约束 |
|---|---|
deploy-admin.sh | 必须有 .tsc-pass(vue-tsc 通过);拒绝"裸 vite build"产物;源码不得新于产物;保留最近 10 份回滚包 |
deploy-server.sh | --no-build 时校验 jar 新于源码(曾发出过旧 jar,靠计数器没降才发现) |
deploy-portal.sh | 发布后断言上传图片真的可访问(含 md5 比对) |
test-migrations.sh / restore-drill.sh | 临时容器用完必须连匿名卷一起清理(曾泄漏 2 个 1.8G 卷) |
11.3 备份与恢复
| 备份 | 频率(cron) | 保留 | 内容 |
|---|---|---|---|
| MySQL 全量 | 每天 03:00 | 7 天 / 7 份(KEEP_DAYS/KEEP_COUNT) | mysqldump 全库 gzip |
| Hindsight | 每天 03:10 | 同上口径 | Postgres dump |
| uploads | 随 MySQL 脚本 | 同上 | 图片资源 |
| 后台发布包 | 每次发布 | 最近 10 份 | 回滚用 tar.gz |
恢复演练:deploy/scripts/restore-drill.sh
- 选最新
db_*.sql.gz→ gzip 完整性检查 → 恢复进临时库restore_drill; - 用同一镜像启动 → 跑 Flyway → 断言版本号、表数、样例行;
- Hindsight:dump → 临时 Postgres → 断言 25 张表且非空;
- 结束时回收匿名卷并校验没有容器/卷泄漏。
⚠️ 已知风险(业主决定暂不处理):所有备份都在同一块盘上, 挡不住磁盘或整机故障。
offsite-readiness.sh会持续显示 BLOCKED(缺 NAS/对象存储客户端)。
11.4 监控与告警
deploy/monitor/health-monitor.sh(cron 定时):
| 检查 | 说明 |
|---|---|
| 健康端点 | /api/health/ready(含依赖检查) |
| 关键页面 | 门户首页、后台入口、/api/portal/site/info |
| 资源 | 磁盘余量、内存、容器状态 |
| 数据 | 备份文件新鲜度、MySQL binlog 体积 |
| 告警 | 微信桥推送(POST 127.0.0.1:8790/notify),失败降级邮件;恢复时补发恢复通知;.alerted 状态文件防重复轰炸 |
11.5 体检(doctor.sh)
25 项检查,覆盖:容器与端口、健康端点、数据库连通与版本、迁移版本、配置键一致性、 上传目录可写、备份新鲜度与构成、告警通道实测、磁盘余量、孤儿匿名卷、时钟与时区、 Nginx 配置单一来源、systemd 残留单元等。期望 PASS=25 WARN=0 FAIL=0。
运行:
bash
bash deploy/scripts/doctor.sh --quiet --mode prod --env-file /opt/vite-cosmos/panel/backend.env11.6 部署脚本全表
见 附录 E。
11.7 生产拓扑与关键挂载
宿主机
├─ nginx(443 → 静态门户/后台;/api → 127.0.0.1:8080)
├─ docker: vite-cosmos-app-prod(host 网络;APP_UID=991)
│ /app/uploads ← /opt/vite-cosmos/uploads(附件/聊天附件)
│ /app/logs ← /opt/vite-cosmos/app/logs
│ /opt/vite-cosmos/... ← 令牌、DSH 工作目录、dsh-profiles、备份目录(只读或读写,见 compose)
├─ docker: cosmos-mysql(127.0.0.1:3307,库 vite_cosmos)
├─ docker: cosmos-hindsight-*(8890,记忆引擎)
├─ dsh web(127.0.0.1:3080,AI 运行时)
└─ systemd/cron:微信桥、健康监控、链路探针、会话采集、DSH 看门狗、备份容器化的坑都写在 deploy/scripts/doctor.sh 与审查记录里,典型三类:
- 路径变了:代码里的
/opt/vite-cosmos/...在容器内不存在 → 必须挂载并在 env 里改容器内路径 (如附件目录COSMOS_CHAT_ATTACHMENT_DIR=/app/uploads/chat-files); - 回环变了:容器内
127.0.0.1不是宿主机 → 桥的推送端点要绑 compose 网关地址; - 权限变了:非 root 运行(uid 991)→ 挂载目录属主必须是
991:1000,令牌文件 640 root:www。
11.8 宿主单元与定时任务
| 单元/定时 | 频率 | 作用 |
|---|---|---|
cosmos-wechat-bridge.service | 常驻 | 微信收发与推送出口 |
cosmos-health-monitor(cron 每分钟) | 1 分钟 | 健康检查 + 邮件/Webhook 告警 |
chain-probe.sh | 5 分钟 | 端到端链路探针(健康 + instructions + MCP 自检) |
collect-sessions.sh | 5 分钟 | 采集 DSH 会话 |
dsh-watchdog.sh | 2 分钟 | DSH 进程看护 |
dsh-workspace-sync.mjs | 5 分钟 | 工作区同步/权限修正 |
dsh-session-rename-guard.mjs | 5 分钟 | 会话命名守卫 |
mysql-backup.sh + backup-hindsight.sh | 每天 03:00 / 03:10 | 备份(本地 7 天/7 份 + 可选异地) |
disk-autoprune.sh | 每 6 小时(<8G 时) | 清构建缓存/旧镜像/旧备份,保底不删最后可恢复点 |
| Hindsight reconcile/monitor/backup timers | 每天/每小时 | 记忆引擎对账、观测、备份 |
11.9 常见运维剧本
| 场景 | 步骤 |
|---|---|
| 发布后端 | mvn -B -o clean test → deploy-server.sh → 健康检查 → 看 10 分钟 ERROR=0 |
| 发布前端 | cd vite-cosmos-admin && npm run build → deploy-admin.sh;门户同理 |
| 迁移数据库 | 只加新迁移;test-migrations.sh 先在临时库跑全量;发布后核对 flyway_schema_history |
| 回滚 | 后端镜像打 tag 保留上一版;deploy-server.sh 可指定镜像;DB 回滚靠备份恢复(谨慎) |
| 恢复演练 | restore-drill.sh 恢复到临时库并核对行数;生产恢复需显式四开关 |
| 附件丢失 | 先查 chat_attachment/sys_file 与磁盘;历史目录用 migrate-chat-attachments.sh 迁移 |
| 微信不收不发 | systemctl status cosmos-wechat-bridge → bridge.log → /health → 重扫码 |
| 记忆异常 | /api/admin/hindsight 看操作/健康;sync-hindsight-token.sh 同步令牌 |