replypier/deploy/server/README.md

从 Gitea 检查并手动更新

部署管理员在 配置 → 系统更新 查看当前版本、Gitea main 最新提交和上次检查时间。有新版本时，顶部也会出现入口。点击“更新到此版本”，确认暂停接待后才开始安装；每 30 分钟的自动检查不会安装或重启应用。

安装到现有 Ubuntu 服务器

本工具适用于 /srv/replypier 的 systemd 部署：replypier-backend、replypier-knowledge，以及 PostgreSQL/Redis 容器。不是 Mac 本机的 Colima 启动脚本。

1. 为服务器创建专用 SSH 密钥，将公钥添加为 Gitea 仓库的只读部署密钥；私钥留在 /etc/replypier-updater/id_ed25519，权限 600。通过可信渠道核实 Gitea 主机公钥并保存为同目录的 known_hosts。更新过程不使用账号密码或浏览器登录态。
2. 按 config.example.json 准备私有配置，填写当前安装提交和部署管理员用户 UUID。只有名单中的用户且持有 super_admin 权限才能更新；其他组织的管理员无权更新整个服务器。配置和 SSH 私钥不入库。
3. 以 root 执行 ./deploy/server/install-updater.sh /path/to/config.json，然后执行 python3 /opt/replypier-updater/cli.py check。安装不会重置应用环境或数据库。
4. Caddy 对稳定文件名的入口返回 Cache-Control: no-cache, no-store, must-revalidate：/sw.js、/manifest.webmanifest、/config.js、/assets/widget.js、/assets/widget.css、/webclient/replypier.min.js。首次设置后，清除 CDN 中这些 URL 的已有缓存；带内容版本号的构建资源可以正常缓存。不要缓存 HTML 入口。

更新时发生什么

• 通过固定的 SSH 仓库获取 main，只接受当前版本的后续提交；仓库历史被重写时停止更新。
• 当前源码若有未同步到 Gitea 的修改，停止更新，先保留并同步修改。
• 在独立目录安装前端依赖、构建控制台和网站组件。后端锁文件有变化时创建独立 Python 环境。准备期间原服务继续运行，磁盘可用空间须至少 4 GiB。
• 暂停业务请求和后台处理，停止应用服务，备份程序及 PostgreSQL；验证备份可读取后才修改在线版本。
• 安装源码、执行 Alembic 迁移、启动服务并检查健康，切换前端后验证入口、JS/CSS 和离线脚本可访问，再恢复接待。公开构建目录设置为 755、文件为 644，私有备份仍由 0077 umask 保护。.env、上传文件、数据库卷和已有运行配置不会被仓库文件覆盖。
• 安装失败时恢复程序和数据库；构建失败不影响在线版本。断电后由开机恢复服务先恢复中断的部署，再启动后端。

更新状态、备份和日志位于 /var/lib/replypier-updater/，由 systemd 服务独立执行，网页关闭或后端重启不会取消更新。备份可能含业务数据，不要公开。备份不自动删除；接近空间下限时更新会停止，管理员确认恢复需求后再清理旧备份。

排查与恢复

systemctl status replypier-update-check.timer replypier-update.service
journalctl -u replypier-update.service -n 60 --no-pager
sudo tail -n 80 /var/lib/replypier-updater/update.log
sudo python3 /opt/replypier-updater/cli.py recover
curl --fail http://127.0.0.1:8018/health

recover 用于仍有维护标记的失败或中断更新。如果自动恢复失败，维护模式保持关闭接待，先检查状态中的备份位置和错误，不要删除维护标记、数据库卷或密钥来绕过恢复。Git 拉取使用只读密钥；发布新版本仍通过正常的 Gitea 提交流程。