服务器准备与部署参数
项目现名「聊记」；历史安装器及合成图示可能显示旧名「留痕」。界面请对照适用版本。
本页目录
本手册的部署主线
主线是 单服务器、单 API 进程、SQLite、Caddy HTTPS。 附件可放外部 S3/COS；内置 MinIO 是可选 profile，默认不启动。 PostgreSQL/S3 是过渡方案，不支持多 API 写入或自动高可用。
服务器源码仓库保持私有，本站不提供公开克隆地址。
先向项目维护者取得可信仓库地址或完整源码包，记录版本、提交和摘要。
需要的是包含 chat-archive/backend、frontend、contracts、
third_party、deploy 的源码，不是 Windows 安装包。
下文假定源码目录为 /opt/liuhen-src；实际放在别处时同步调整。
恢复或生产升级不能使用“未记录版本的某个源码压缩包”。
Windows 取得的 Linux shell 脚本必须保持 LF，否则容器可能报解释器不存在。
服务器环境
| 条件 | 检查方式 | 不满足时 |
|---|---|---|
| Linux 服务器 | 查看系统发行版与架构，使用受 Docker 支持的平台 | 本手册不承诺所有系统或 ARM 构建均完成验证 |
| Docker Engine 与 Compose plugin | docker version、docker compose version | 必须能联系 daemon；CLI 存在不等于服务可用 |
| 管理权限 | 具有部署目录、Docker 和网络配置权限 | 默认用经授权的管理员 shell；不要随意给其他用户 Docker 权限 |
| 域名 | archive.<根域名> 指到服务器 | DNS 与云安全组、宿主机监听分别检查 |
| 存储 | 本地持久化盘、可用空间足以容纳数据库与快照 | 不把 SQLite 卷放 NFS/SMB，不用空闲空间的固定比例假定安全 |
| 独立备份 | 附件与备份分桶，恢复凭据保存在独立密码管理器 | 同机 MinIO 和一个 Docker 卷不构成异地灾备 |
Ubuntu 安装 Docker 使用Docker 官方安装说明。 按自己的系统版本配置官方软件源，安装 Engine 与 Compose plugin； 生产部署不以一键便利脚本替代明确的版本和安装方式。 Docker 发布端口可能绕过 ufw 的常规规则，需同时核对 Docker 与云侧入口。 环境与应用锁参数核对于2026-10-18，不是本手册基线核对时安装结果。
.env 参数
从 chat-archive/deploy/self-hosted/.env.example 复制为 .env，
使用编辑器填写；没有要放进此文件的长期 COS 密钥。
示例域名与邮箱必须换成自己控制的实际值。
| 参数 | 示例或默认 | 含义 |
|---|---|---|
| CHAT_ARCHIVE_DOMAIN | example.com，需替换 | 入口为 https://archive.example.com:8443 |
| CHAT_ARCHIVE_ACME_EMAIL | 自己的证书联系邮箱 | Caddy 自动签发与续期使用 |
| CHAT_ARCHIVE_API_PORT | 8080 | 宿主机回环 API 端口，不是公网端口 |
| CHAT_ARCHIVE_RELEASES_DIR | ./releases | 公开桌面更新文件目录，只读挂到 Caddy |
| CHAT_ARCHIVE_WEBAUTHN_RP_ID | 自己的域名，不含协议端口 | 应用锁的RP ID，仅自托管 |
| CHAT_ARCHIVE_WEBAUTHN_ORIGINS | 完整HTTPS来源，含实际端口 | 设备验证允许来源，须由Compose转交API |
| COMPOSE_PROJECT_NAME | 首次自行定名，例如 liuhen-prod | 数据卷与容器命名；生产后不要随意修改 |
| CHAT_ARCHIVE_ROTATION_USER | 原生 Linux 使用文件拥有者 UID:GID | 只影响可选轮换任务，不在日常升级中随便执行轮换 |
Compose 文件已有 name: chat-archive-self-hosted；没有覆盖项目名时使用它。
改变项目名会让 Compose 寻找另一组卷，可能看起来像“档案突然没了”。
不要把改变项目名当成普通重启。
端口与存储边界
| 入口或卷 | 当前配置 | 用途与限制 |
|---|---|---|
| 80/TCP | Caddy 公网发布 | HTTP-01 证书验证与跳转；续期同样需要，不能首签后永久关闭 |
| 8443/TCP | Caddy 公网发布 | 归档 HTTPS；当前方案不占用 443 |
| 9443/TCP | Caddy 公网发布 | 可选 MinIO 的 HTTPS 附件入口；仅显式MinIO组合使用，默认/COS不公布 |
| 127.0.0.1:8080 | 宿主机回环映射 | 本机健康检查；不要改为公网绑定 |
| api_data | 持久化命名卷 | 归档与认证等状态；不能用 down -v 删除 |
| minio_ca | CA 与公共根的 bundle | 即使用 COS 仍需要 cert-init 生成 |
| caddy_data、caddy_config | Caddy 状态卷 | 证书与配置状态，升级时保留 |
| minio_data | 内置 MinIO 对象卷 | 仅启用 MinIO 时存在用途，单卷本身不是灾备 |
API 在容器网络内监听 0.0.0.0:8080 是容器内部设置；
“只发布到回环”说的是宿主机 ports 映射。不要把两者混为配置矛盾。
MinIO 自身不直接发布端口，外部访问通过 Caddy。
认证与凭据
| 对象 | 来源 | 管理方式 |
|---|---|---|
| 首台设备 token | provision 输出一次 | 作为秘密保存，仅交给授权桌面采集端 |
| 网页引导令牌 | 当前 API 启动后的 bootstrap 文件 | 仅初始设置使用，不能当设备 token |
| 网页口令与两步恢复码 | 首次网页向导设置 | 不存在默认密码；恢复码只显示一次 |
| 对象存储凭据 | 云侧最小权限子账号 | 在设置页测试后加密保存，不填 Compose 环境变量替代配置 |
| 备份凭据 | 独立备份桶的子账号 | 配置入口或只读凭据文件；不进命令行参数值和日志 |
应用锁默认关闭；未配置RP ID和允许来源时，开关不可用。 改.env后需按运维流程使容器收到变量，文件保存不代表配置已生效。
PostgreSQL/S3 过渡方案
deploy/postgres-s3 用 PostgreSQL 存业务元数据，认证与 blob 状态仍有 SQLite 控制库。
它与 SQLite 主线的备份格式不同，不能使用 SQLite 的一条恢复命令代替 PITR。
| 项目 | PostgreSQL/S3 要求 |
|---|---|
| 启动 | 初始化凭据，填写自己的 .env，解析 config 后 up -d --wait api |
| HTTPS | 该 profile 没有同等 Caddy 服务，由同主机独立 HTTPS 反代管理 |
| 一致恢复点 | PostgreSQL 备份、控制库快照与版本化对象清单必须匹配 |
| 创建恢复点 | 使用 orchestrate-recovery-point.py，停 API 的全过程由编排器管理 |
| 恢复 | 全新 PostgreSQL、控制状态、marker 三组命名卷，恢复 profile 保持隔离 |
| 验收 | WAL、A/B 事务目标时间、控制库与对象版本双向核验；配置解析不证明 PITR |
| 切换 | 恢复不会自动晋升；需旧主隔离、凭据与客户端游标策略 |
该方案完整命令的技术真源仍是项目 deploy/postgres-s3/README.md。
本手册基线核对时只解析配置，没有运行 PostgreSQL、MinIO、pgBackRest 或异地恢复。
Cloudflare Workers 的生产部署也未在本手册基线核对时验证，不把这些运行时写成同一个能力集合。