Skip to content

十一、部署与运维 ​

本章速览:读完后你会知道 —— ① 生产拓扑、容器与关键挂载(改路径/回环/权限最容易踩坑);② 发布、回滚、迁移、备份与恢复的标准流程;③ 监控、体检(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:007 天 / 7 份(KEEP_DAYS/KEEP_COUNT)mysqldump 全库 gzip
Hindsight每天 03:10同上口径Postgres dump
uploads随 MySQL 脚本同上图片资源
后台发布包每次发布最近 10 份回滚用 tar.gz

恢复演练:deploy/scripts/restore-drill.sh

  1. 选最新 db_*.sql.gz → gzip 完整性检查 → 恢复进临时库 restore_drill;
  2. 用同一镜像启动 → 跑 Flyway → 断言版本号、表数、样例行;
  3. Hindsight:dump → 临时 Postgres → 断言 25 张表且非空;
  4. 结束时回收匿名卷并校验没有容器/卷泄漏。

⚠️ 已知风险(业主决定暂不处理):所有备份都在同一块盘上, 挡不住磁盘或整机故障。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.env

11.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 与审查记录里,典型三类:

  1. 路径变了:代码里的 /opt/vite-cosmos/... 在容器内不存在 → 必须挂载并在 env 里改容器内路径 (如附件目录 COSMOS_CHAT_ATTACHMENT_DIR=/app/uploads/chat-files);
  2. 回环变了:容器内 127.0.0.1 不是宿主机 → 桥的推送端点要绑 compose 网关地址;
  3. 权限变了:非 root 运行(uid 991)→ 挂载目录属主必须是 991:1000,令牌文件 640 root:www。

11.8 宿主单元与定时任务 ​

单元/定时频率作用
cosmos-wechat-bridge.service常驻微信收发与推送出口
cosmos-health-monitor(cron 每分钟)1 分钟健康检查 + 邮件/Webhook 告警
chain-probe.sh5 分钟端到端链路探针(健康 + instructions + MCP 自检)
collect-sessions.sh5 分钟采集 DSH 会话
dsh-watchdog.sh2 分钟DSH 进程看护
dsh-workspace-sync.mjs5 分钟工作区同步/权限修正
dsh-session-rename-guard.mjs5 分钟会话命名守卫
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 同步令牌

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。