首次部署自托管服务器

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

前置条件

• 已按服务器准备取得可信源码与可用 Docker。
• 域名指向服务器，80、8443 可达；MinIO 分支另需 storage 域名及 9443。
• 命令在新的 Linux 部署执行，不对已有生产卷重复置备。

起点：服务器终端位于源码的 chat-archive/deploy/self-hosted，尚无生产 API。

初始化部署

1. 复制并编辑配置，域名、邮箱换成自己的值：

   cp .env.example .env
   mkdir -p releases
   nano .env

2. 选择存储分支并检查配置。COS 分支不初始化 MinIO 秘密文件；内置 MinIO 分支先设置：

   # 仅内置 MinIO；COS 分支跳过下面三行
   export COMPOSE_FILE=compose.yaml:compose.minio.yaml
   export COMPOSE_PROFILES=minio
   python3 initialize-secrets.py
   docker compose --env-file .env config --quiet

   这是当前源码可选配置；后续命令保持同一 COMPOSE_FILE 与 profile。默认/COS 不公布 9443。
3. 显式构建并初始化卷及证书：

   docker compose --env-file .env build api cert-init data-init
   docker compose --env-file .env run --rm data-init
   docker compose --env-file .env run --rm cert-init

4. 仅使用内置 MinIO 时执行：

   docker compose --env-file .env --profile minio run --rm minio-init

   • 预期：初始化成功；COS 分支仍需 cert-init，不必启动 MinIO。

置备与网页首次设置

起点：持久化卷已初始化，API 未启动。

1. 创建首个归档与设备：

   docker compose --env-file .env run --rm api \
     python -m chat_archive.server.cli provision \
     --archive-id archive_personal --archive-name "个人归档" --device-name "首台设备"

   device_token 只显示一次，保存到密码管理器，不转发终端日志。
2. 启动服务：

   docker compose --env-file .env up -d --wait api caddy
   docker compose --env-file .env ps

3. 在服务器终端读取启动后有效的网页引导令牌：

   docker compose --env-file .env exec -T api \
     cat /var/lib/chat-archive/browser-bootstrap-token

4. 浏览器打开自己的 HTTPS 地址，完成初始口令和可选两步验证。
   • 预期：首次向导关闭，以后用网页口令登录，不用设备 token 登录。

接入首台 Windows 电脑

起点：已保存 provision 返回的 archive_id、device_id、device_token，电脑已安装聊记。

1. 在这台 Windows 电脑的 PowerShell 运行安装版模块入口：

   & "$env:LOCALAPPDATA\Programs\chat-archive\runtime\python.exe" -m chat_archive.local.remote_cli adopt `
     --base-url https://archive.YOUR_DOMAIN:8443 `
     --archive-id archive_personal --device-id YOUR_PROVISIONED_DEVICE_ID

   换成自己的域名、archive_id 和 device_id；不要把 token 放到命令参数。
2. 出现 device token 提示后，在终端输入一次性 token 并按 Enter。 交互式终端使用遮罩输入；避免旁观和录屏，不把token写进参数。
3. 刷新聊记 接入远程档案 页，确认已接入，再运行同步。
   • 预期：本机安全存储保存设备凭据；后续电脑可用该设备生成的配对码。

验证

检查 curl --fail http://127.0.0.1:8080/api/v1/health、浏览器 HTTPS、登录， 再按同步接入首台桌面设备并配置附件存储。 本手册基线核对时核对当前配置和命令，未执行首次部署或访问真实桶。 历史合成/容器检查见版本与验证边界，不构成本次DNS/ACME、MinIO或真实账号验收。一次性初始化使用 run --rm，不对已退出任务使用 up --wait。

失败时

DNS、端口、权限与证书问题见服务器运维。 重启尚未初始化的 API 会使旧引导令牌作废，需启动后重新读取。 恢复已有档案走隔离恢复，不重复 provision。