服务器巡检、升级与回滚

项目现名「聊记」；历史安装器及合成图示可能显示旧名「留痕」。界面请对照适用版本。

前置条件

• 明确生产目录、项目名、数据卷与当前版本。
• 升级前已有深校验备份；维护窗口已安排。
• 以下是操作指引，本手册基线核对时没有执行生产停机、升级或回滚。

起点：服务器终端位于生产 deploy/self-hosted 目录。

日常巡检

1. 检查服务与回环健康：

   docker compose --env-file .env ps
   curl --fail http://127.0.0.1:8080/api/v1/health
   df -h
   free -m

2. 查看必要日志：

   docker compose --env-file .env logs --tail=100 api caddy

   初始令牌和分享链接可能出现在日志中，转发前脱敏。
3. 浏览器检查 HTTPS、登录、新消息与附件，再检查备份和深校验时间。
   • 预期：进程、服务响应、业务读取与备份分别成立，不以 running 代替业务核验。

升级并保留旧镜像

起点：已完成备份校验，候选版本在隔离环境验证过。

1. 记录当前源码、配置、卷与镜像 ID，保留旧镜像：

   current_image=$(docker compose --env-file .env images -q api)
   test -n "$current_image"
   docker image tag "$current_image" liuhen-api:rollback-before-upgrade

2. 使用已核验的候选源码构建：

   docker compose --env-file .env build api

3. 保持项目名和数据卷，重建 API：

   docker compose --env-file .env up -d --no-deps api

4. 等 API 健康，重复巡检并确认版本与业务。
   • 预期：新程序运行，档案卷保留；不要改项目名或删卷代替升级。

回滚与认证恢复

原数据兼容时，新建 rollback.yaml：

services:
  api:
    image: liuhen-api:rollback-before-upgrade

按已保存的旧镜像回退：

docker compose --env-file .env -f compose.yaml -f rollback.yaml up -d --no-build --no-deps api

应用锁已开启时，不能直接退到不执行应用锁门禁的旧版。 先确认目标版保留门禁；确需退至旧版时，维护窗口先关闭或重置并告知保护消失。 关闭清除的登记不会因回退代码恢复。

数据库迁移后旧镜像未必能读新库；不兼容则隔离并恢复匹配备份。

忘记网页口令时，在维护窗口停止 API，再运行 reset-browser-login，重启后取新令牌：

docker compose --env-file .env stop api
docker compose --env-file .env run --rm api python -m chat_archive.server.cli reset-browser-login
docker compose --env-file .env start api

此操作清除口令、两步绑定和浏览器会话；已有授权后才执行，不在运行中的 API 内 exec。

应用锁不能在线重置时，由管理员在维护窗口停止API后运行：

docker compose --env-file .env stop api
docker compose --env-file .env run --rm api python -m chat_archive.server.cli reset-browser-reauth
docker compose --env-file .env start api

此入口重置应用锁并撤销浏览器会话，需重新登录； 与清除网页登录口令的 reset-browser-login 不同。

验证

记录镜像、版本、健康、消息与附件。本手册基线核对时仅配置核对，未实机验收回滚。

失败时

502 查 API 与代理；附件 403 查 Host、凭据与存储代号；TLS 错误查 CA，不关闭验证。 停止用 docker compose --env-file .env down，不要加 -v。