DEPLOY.md

Rama main · réplica de lectura del repositorio original.

# NovelWorld 部署指南

> 当前支持边界是管理员控制的私有单节点自托管预览。默认仅限 localhost；任何
> 非本机访问必须由管理员提供加密隧道或 TLS 边界。
> 默认栈没有通过公网托管所需的 TLS、CORS、滥用治理、内容政策、法务和持续运维
> 资格审查。完整边界见 [产品合同](./docs/PRODUCT_CONTRACT.md)。

Compose 默认发布 `127.0.0.1:80`。如需调整，在私有 `.env` 中显式设置
`NGINX_HTTP_BIND` 和 `NGINX_HTTP_PORT`。只有在管理员已配置加密私有网络或 TLS
入口时，才将绑定地址改为所需的私有接口；更改绑定地址或端口本身不会启用 TLS。

## 系统要求

| 组件 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | 2 核 | 4 核+ |
| 内存 | 4 GB | 8 GB+ |
| 磁盘 | 20 GB SSD | 50 GB SSD |
| 操作系统 | Windows 10/11、Ubuntu 22.04、Debian 12 | Windows 11、Ubuntu 24.04 |
| Docker | 24.0+ | 最新稳定版 |
| Docker Compose | 2.20+ | 最新稳定版 |

---

## 快速部署

服务端可选择下方的直接启动方式，或使用 [Jenkins 服务端部署](#jenkins-服务端部署可选)。
Jenkins 仅是可选的服务器部署入口；本地启动、桌面版和其他部署方式由用户自行选择。

### 第 1 步：安装 Docker

Windows 请安装并启动 [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)。
Linux 可运行：

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
```

### 第 2 步：克隆代码

```bash
git clone https://github.com/Wisdoverse/novelworld.git
cd novelworld
```

### 第 3 步：一条命令启动

```bash
# Linux
./start.sh
```

Windows 在命令提示符运行，或在资源管理器中双击：

```bat
start.cmd
```

首次交互启动会引导确认 L0 所需的 PostgreSQL 用户名和数据库名，自动生成数据库
密码，最后写入 `BOOTSTRAP_L0_COMPLETE=true`，并在任何容器启动前自动重启
启动器一次。有效的旧版或预配置 `.env` 会无提示迁移；未完成配置的非交互启动
会明确失败并要求预置 `POSTGRES_USER`、`POSTGRES_DB` 和强密码。

重启后脚本只自动生成 JWT、配置加密和服务间鉴权所需的 L1 启动根。
新安装默认持久化 `CACHE_MODE=postgres`，不生成 Redis 密码，也不启动 Redis。
脚本使用 Compose `--wait`，只在整个选定 profile 达到 readiness 后才打开
`http://localhost`。先创建唯一的首位管理员；DeepSeek/OpenAI 可稍后在设置页
配置，API Key 不会保存在浏览器中。

首次构建约需 5-15 分钟（Rust 编译较慢）。

### 第 4 步：验证部署

```bash
# 检查基础 profile 状态
docker compose ps

# 通过公开 Nginx 入口检查聚合健康
curl --fail http://localhost/health
curl --fail http://localhost/ready

# 查看日志
docker compose logs -f gateway

# 按 .env 中的 CACHE_MODE 检查；Redis 仅在 redis 模式中是必需健康项
./infra/ops/health-checks.sh
```

默认仅在本机通过 `http://localhost` 访问；非本机访问必须先增加加密传输边界。
首次访问只需创建唯一的首位管理员。未配置 LLM 时基础服务仍可 ready，
国内模型 API、Coding/Token Plan 的中国版与国际版在 Settings 中分开选择；
各版本的端点、模型和 Key 说明见 [LLM 服务商配置](./docs/LLM_PROVIDERS.md)。
切换服务商、地区或套餐须重新填写 Key，套餐耗尽不会自动转到普通 API。

AI 操作返回明确的 `503 llm_not_configured`。LLM 密钥由 User Service 加密保存
或从环境变量读取，浏览器不会保存密钥。

### 显式启用 Redis 投影

在 `.env` 中同时设置 `CACHE_MODE=redis` 和至少 16 位、包含至少 8 种字符的
URL-safe `REDIS_PASSWORD`（`A-Z a-z 0-9 . _ ~ -`），再重新运行 `start.sh` 或
`start.cmd`。脚本会由该唯一 mode 同时派生 Redis profile 和 `REDIS_URL`；
缺密码、占位值、未知 mode 或只选中一半都会拒绝启动。旧版启动器已
生成 Redis 密码但没有 `CACHE_MODE` 的安装，首次运行新脚本会一次性持久化
`redis`，避免升级后静默切换适配器。

Redis 为 Agent Service 提供可重建的消息投影，不承接小说解析队列。上传接收后
持久化的 PostgreSQL 导入任务通过 claim、lease 和恢复扫描等待解析槽位；解析
繁忙不阻止有接收容量的新书入队。批量上传最多选择 50 本，浏览器按每批最多
5 本、合计 40 MiB 顺序发送。共享书库可直接添加已有 Ready 小说，避免重新
上传和解析；尚未提供自动文件哈希去重。

### 显式启用 RustFS 原文件存储

RustFS 使用已有 S3 适配器，由管理员独立部署；仓库 Compose 不会自动创建
RustFS 容器或 bucket。为其固定镜像 digest、配置独立持久化数据卷，并让
Novel Service 通过共同的私有 Docker 网络访问。无需向宿主机发布 S3 或
控制台端口；应用凭据与管理员 root 凭据分开保管。

例如容器网络别名为 `novel-rustfs`、S3 端口为 `9000` 时，在私有 `.env` 设置：

```dotenv
S3_ENABLED=true
S3_ENDPOINT=http://novel-rustfs:9000
S3_BUCKET=novel-world-uploads
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true
```

先创建 bucket，再从本地秘密配置填写配套的 `S3_ACCESS_KEY` 与
`S3_SECRET_KEY`；长期应用账户的 `S3_SESSION_TOKEN` 留空。此 HTTP 示例仅用于
同主机私有容器网络；跨主机连接须提供受信任 TLS 边界。不要在容器里使用
`127.0.0.1` 指向另一容器，也不要提交 `.env` 或在命令输出中展示凭据。

应用账户仅需 bucket 上的 `s3:ListBucket`，以及该 bucket 的 `source-files/*`
对象上的 `s3:GetObject`、`s3:PutObject`、`s3:DeleteObject`。`ListBucket` 用于
`HeadBucket` readiness，不能加上只适用于列举对象的前缀条件而阻断 HEAD。
RustFS 服务账户继承父账户权限：给父 IAM 用户附加上述最小权限策略，或在创建
派生服务账户时附带限制性的 session policy；不要把服务账户当作独立 IAM 用户
直接绑定策略。须检查最终生效权限，见
[官方 IAM 说明](https://docs.rustfs.com/en/security-compliance/iam)。

按受管部署流程重建 Novel Service 后，验证其 `/ready`、用应用账户执行
HEAD 和一次私有测试对象的 PUT/GET/DELETE，并确认前缀外对象与其他 bucket
访问被拒绝。不得用真实小说解析来代替存储探针。启用只保留之后上传的原文件，
不会为历史上传补齐源对象；原文件保留不等于自动去重。已保留源对象的恢复、
删除仍需要此 bucket，停用前需明确这些任务的处理方式。PostgreSQL 备份不含
RustFS 数据卷，管理员须单独安排对象存储备份与恢复，见
[备份边界](./docs/BACKUP_RESTORE.md#scope)。

---

## 同一世界剧情来源迁移 0036

0036 新增 Narrative 所有的来源操作记录和可空的回合来源坐标，不重写旧世界
JSON。首次明确进入下一幕后，session 使用 schema v2 和独立 active source context；
原始 entry、角色、规则和旧回合保留。使用现有 managed release 流程停止旧
Narrative，再发布客户端，停止并 drain Novel/Agent，执行 migration 后启动匹配版本。
新 UI 只能配合支持来源扩展的 Novel/Narrative 使用。

release 的五个 barriers 必须齐全。即使 0036 SQL 是 additive，也不能在世界扩展后
恢复旧 Narrative reader；rollback/marked restore 拒绝跨过 0036。保留数据库与操作
key，通过兼容版本向前恢复，不能删除 source_context、重置角色或手写 JSON 回退。
读取进度后退时只隐藏后续派生内容，不能删除已接入来源。
参见 [ADR 0013](docs/adr/0013-same-world-source-progression.md)。

---

## Jenkins 服务端部署（可选）

仓库根目录的 [`Jenkinsfile`](./Jenkinsfile) 在 Linux 私有单节点服务器上构建并自动
部署六个应用镜像。代码、架构、测试和秘密扫描检查由现有 GitHub Actions CI 负责；触发
Jenkins 前，应确认选用的受信任分支或提交已通过 CI。每次成功构建都会运行现有
`start.sh`，随后执行 `infra/ops/health-checks.sh`，确认部署 readiness 和部署后健康状态。
部署依赖 Job 默认 workspace 中预先配置且跨构建保留的 `.env`；缺少时，镜像构建前
即失败关闭。Compose 使用该 `.env` 构建和启动，不使用示例配置。

若服务器需要本机网络或挂载配置，在同一 workspace 根目录保留私有的
`docker-compose.override.yml`。构建、启动和镜像核验都会由 Compose 自动读取该文件。
该文件与 `.env` 一样不进入 Git，也不进入根目录的 Docker 构建上下文；不要把它加入
构建归档。源码检查仍拒绝其他未忽略文件和已修改的受跟踪文件。

每次成功部署应在 Job 的默认 workspace 中归档
`.local/jenkins-deployment/deployment.tsv`：记录干净检出的完整 Git SHA，以及
`gateway`、`user-service`、`novel-service`、`agent-service`、`narrative-service` 和
`frontend` 各自的构建镜像 ID 与部署容器 ID。首次成功部署也按此方式记录；每次运行都应
先移除 workspace 中旧的未归档记录，并在 `start.sh`、readiness 和健康检查全部成功后
生成记录。健康检查后，应确认每个部署容器仍使用对应的构建镜像 ID，再归档完整记录；
失败时不得留下可被误认为成功的部分记录。若部署已成功但记录或归档失败，先检查当前
服务状态和镜像身份，再决定是否重试；此流程不会自动回滚或重置安装。

该记录只提供受信任单写入者部署流程的观察证据，不是隔离构建、可复现构建、签名或
正式来源证明；不得据此追认旧构建。记录中的 SHA 只证明已检出提交及其受跟踪文件干净，
不证明默认 workspace 内被忽略的本地文件、环境或 Docker 主机状态。
其中也包括 `docker-compose.override.yml`；运维者须单独审查和保留该配置。

1. 在目标 Linux 部署服务器安装 Git、Bash、OpenSSL、curl，以及带 BuildKit 的
   Docker 和 Compose v2。Jenkins agent 用户必须能访问该服务器的 Docker daemon。
   Jenkins 主机无需安装 Rust、Node.js、pnpm 或 Python；镜像所需的 Rust、Node.js
   与 pnpm 工具链由 Dockerfiles 在容器内提供。
2. 创建 **Pipeline script from SCM** 作业，选择本仓库的受信任分支，Script Path 为
   `Jenkinsfile`；需要 Jenkins Pipeline、Git 和 Timestamper 插件。此作业必须专用于
   受信任分支，不运行外部 PR。由于流水线使用 `agent any`，所有符合条件的 executor
   都必须位于同一 Linux 部署服务器并使用同一 Docker daemon。Pipeline 使用 Jenkins
   分配给该 Job 的默认 workspace；确保它在该服务器上跨构建保持不变。
   部署前应确认所选受信任分支或提交已通过 GitHub Actions CI；Jenkins 只负责镜像
   构建和部署。
3. 在首次构建前，于 Job 的默认 workspace 内私下配置 `.env`：可复制 `.env.example`，填写有效的
   `POSTGRES_USER`、`POSTGRES_DB` 和满足启动器要求的强 `POSTGRES_PASSWORD`，
   设置 `BOOTSTRAP_L0_COMPLETE=true`，权限设为 `600`。启动器会生成缺少的 L1 根；
   之后应保留这些值，LLM 可稍后在设置页配置。Redis 仍由 `CACHE_MODE` 决定。
   不要启用 SCM 清理未跟踪文件，也不要清理 Job 的默认 workspace；`.env` 中的数据库
   密码和启动根必须跨构建保留。不要把 `.env` 放入 Git、Jenkins 参数、日志或构建归档。
4. 确认已通过 GitHub Actions CI，准备维护窗口和已验证的数据库备份后，运行 Job。
   Jenkins 调用 `start.sh` 先构建镜像；构建失败时旧容器仍保持运行。构建成功后才停止
   旧 writer，再以不重复构建的方式启动完整栈并重放迁移。Compose 等待 readiness 后再
   通过入口与容器健康检查。每次部署会造成停机；配置不完整、构建失败或健康检查失败
   都会使作业失败。

已有源码安装接入前，先在私有 `.env` 中设置与该安装完全相同的
`COMPOSE_PROJECT_NAME`（当前安装为 `novel-world`），并保留原有的
`POSTGRES_USER`、`POSTGRES_DB`、`POSTGRES_PASSWORD`、`BOOTSTRAP_L0_COMPLETE`、
`JWT_SECRET`、`RUNTIME_CONFIG_KEY` 和 `INTERNAL_SERVICE_TOKEN`。这样 PostgreSQL 数据卷
仍由原 Compose project 管理，启动根也保持不变；不要执行数据卷迁移或重新初始化。
新建安装可不设置 `COMPOSE_PROJECT_NAME`，Compose 会沿用 Job 默认 workspace 的名称，
该 workspace 必须跨构建稳定。若 Jenkins agent 在容器中，确保 Docker daemon 可访问
到相同 workspace 路径，使构建上下文和 Compose bind mounts 指向正确位置。
健康检查默认访问 `http://127.0.0.1:80`；若该地址不能从 Jenkins agent 到达，可在私有
`.env` 配置未加引号的 `NGINX_URL=http://...`，指向该 agent 可访问的部署入口。该 URL
只用于 Jenkins 发起的部署后探测。每个服务器仍只配置一个作业，流水线禁止并发运行。
服务端仍默认仅在 localhost 访问，远程访问使用既有加密边界。

此入口沿用直接启动器的源码安装流程，没有自动回滚。遇到失败先排查迁移和健康
状态，不自动重跑或删除数据卷。存在 `.release` 的受管安装在检出前会被拒绝，仍按
下方的不可变 `release.env` 升级、确认与恢复流程处理；不可用源码启动绕过该契约。

---

## D20 基础规则迁移 0030

0030 改变 Novel Service 的模板写入契约，旧 Novel writer 与新 schema 不兼容。
升级时先关闭入口写入并停止、排空 Novel 和 Narrative 两个服务；不能只停
Narrative。候选 release 必须包含完整的 0021、0024、0025、0030、0036 五个 required
schema barriers；应用完整候选 release 后再启动兼容版本，避免旧 writer 在迁移后写入。现有 v1 profiles 和 sessions 保留原绑定，继续按 v1 读取；
不要重写为 v2。数据库只前向迁移，旧版 rollback 不受支持，故障恢复使用兼容
release 前向修复。此要求是 rollout 契约，不代表该迁移已在生产执行。

每次受管部署都会重放标准迁移目录。导入可在章节可用前原子创建默认
`reading_progress`；`current_chapter = 1` 只是元数据，不证明该章节存在。
迁移 0002 对 `pending`、`parsing`、`error` 且在公布章节数内没有有效章节的小说
保留进度及其偏好；`ready` 或状态缺失/未知而没有有效章节时必须失败关闭，且只可
按现有有效章节规范化。升级前先完成并验证 PostgreSQL 备份，不要手动删除或改写
进度记录来绕过迁移错误。当前一键 `start.sh` 会先构建所选 profile 的镜像；若构建失败，
旧容器仍保持运行。构建成功后才执行 `docker compose down`，再用 `up --no-build` 启动完整
栈并重放迁移；它不是只重开入口的命令。

迁移 0019 只在首次引入 `user_novels` 关系时回填上传者书架：它在创建关系之前记录该表
是否已存在，并在事务内锁定 `novels`。若表原已存在（即使为空），重放保留现有书架，
不会把已移出的书重新挂回上传者。此检查用于区分首次采用与重放，不会自动修复任意
历史部分迁移。`tests/integration/tests/legacy_migration.rs` 中的全迁移重放回归覆盖显式移除
后的保留行为；Issue #424 记录最终 CI 与 live 部署证据。

若受管停机后只需重开已经存在的 Nginx 容器，本机 Compose `start --help` 不提供
`--no-deps`；确认只返回一个 Nginx 容器 ID 后再使用：

```bash
nginx_id=$(docker compose ps --all -q nginx)
test -n "$nginx_id" && test "$(printf '%s\n' "$nginx_id" | wc -l)" -eq 1 && docker start "$nginx_id"
```

## 生产升级与回滚

Rust 原生镜像的源码新鲜度属于构建阶段契约，不是部署脚本可补救的事项。
构建必须在现有锁定的 BuildKit Cargo target cache 内只清理 workspace release
产物（`cargo clean --locked --release --workspace`），保留第三方已编译依赖及
registry/layer cache，不清理宿主机共享 Cargo target。历史 git archive 的源码
mtime 可能让 Cargo 复用其他 revision 编译的 workspace 二进制；Docker `RUN`
成功本身不能证明二进制对应当前源码。发布证据必须证明 Cargo 实际编译了变更源码。
对注册候选 release pair，B 的真实 runtime 变更至少须使一个受影响应用镜像的
image ID 和至少一个 filesystem layer 均与基线不同；仅文档/缓存变化或未改变的
runtime 输入不要求每个镜像或二进制都变化。当前 #432 与 #429 的交付顺序是 A→C→B；
只有实际合并的 C 基线和其严格后继 B 候选、且两端都含该保护，才可参与
后续 artifact pair 资格验证。旧 A 基线和失败预览产物须保留为失败证据，且不合格。

`v*` Tag workflow 会先运行完整 CI，只发布以 Git SHA 标记的应用镜像。
全部镜像和 Windows/Linux/macOS 客户端构建成功后，同一 GitHub Release
会附加 `release.env`、SBOM、客户端压缩包、`desktop-SHA256SUMS` 和
`release-attestation.json`。发布文件的逐文件 provenance 验证流程见
[`SECURITY.md#release-file-provenance`](SECURITY.md#release-file-provenance)。
`release.env` 只允许版本、代码 SHA、六个应用镜像和三个经源码审批的
基础镜像 digest；不要部署单个镜像或使用 `latest`。

消费者必须使用独立复核取得的 source/signer SHA，并独立取得 trusted roots；不能
只信 `release.env` 或随 release 附带的 root。当前 `release.sh` 仍不会自动执行
provenance 或 deploy-time SBOM admission，相关 H2 证据仍待完成。

PostgreSQL、Redis、Nginx 的 digest 固定在 `docker-compose.yml`。普通应用发布
要求候选与当前 release 的三个 digest 完全一致，总是检查 PostgreSQL，
只在 `CACHE_MODE=redis` 时检查 Redis，
不会重建或降级它们。基础镜像变更必须作为独立基础设施变更，先完成数据库备份、
格式兼容与恢复演练；本脚本会拒绝把它混入应用发布。

Redis 7 到 8 是一次冷切换，不是普通 `release.sh upgrade`。本次切换只适用于
尚无用户的默认 Unix 预览环境。`CACHE_MODE=redis` 的受管安装使用以下一次性
流程；不要 `source` manifest：

```bash
set -euo pipefail
target=/absolute/path/to/redis8-release.env
repo_root=$(git rev-parse --show-toplevel)
cd "$repo_root"
archive_root="$(dirname "$repo_root")/novelworld-release-archive"
install -d -m 700 "$archive_root"
./infra/docker/release.sh validate "$target"
docker compose --env-file .env --env-file .release/current.env --profile redis \
  stop nginx gateway agent-service redis
redis_volume=$(docker inspect --format \
  '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}' novel-redis)
redis_project=$(docker inspect --format \
  '{{ index .Config.Labels "com.docker.compose.project" }}' novel-redis)
test -n "$redis_volume" && test -n "$redis_project"
test "$(docker volume inspect --format \
  '{{ index .Labels "com.docker.compose.volume" }}' "$redis_volume")" = redis_data
test "$(docker volume inspect --format \
  '{{ index .Labels "com.docker.compose.project" }}' "$redis_volume")" = "$redis_project"
docker compose --env-file .env --env-file .release/current.env --profile redis rm -f redis
archive="$archive_root/redis7.$(date -u +%Y%m%dT%H%M%SZ)"
test ! -e "$archive"
mv .release "$archive"
sync
docker volume rm "$redis_volume"
unset REDIS_IMAGE COMPOSE_PROFILES
docker compose --env-file .env --env-file "$target" --profile redis pull redis
docker compose --env-file .env --env-file "$target" --profile redis up -d --wait redis
./infra/docker/release.sh adopt "$target"
```

仓库外的 `.release` 归档是删除卷前的单向提交点；之后不得恢复其中的 Redis 7 manifest。
`adopt` 会拒绝运行中 Redis 与目标 exact image 不一致的情况。失败时保持入口关闭
并只向 Redis 8 重试。不得使用 `down -v`，PostgreSQL 卷必须保留。
`CACHE_MODE=postgres` 没有运行中的 Redis，只需停入口和应用、归档旧 release
状态并重新 `adopt`。新安装直接采用 Redis 8。任何已有用户、Windows 原地升级
或需保留 Redis 投影的环境都不在本次批准范围内，必须另行设计并验证迁移。

自动回滚只适用于新格式 release。如果当前环境已经使用九镜像契约，首次采用前先
验证一份与实际代码和镜像完全一致的基线：

```bash
./infra/docker/release.sh validate /path/to/current-release.env
install -d -m 700 .release
install -m 600 /path/to/current-release.env .release/current.env
```

旧版 all-in-one 环境无法建立上述基线。此时必须先保留并验证旧源码 bundle、精确
镜像和数据库备份的人工恢复路径，再执行一次性采用；按提示输入
`ADOPT-<release-git-sha>`。采用成功只建立 current，不伪造 previous，因此自动
rollback 要到下一次成功 upgrade 后才可用：

```bash
./infra/docker/release.sh adopt /path/to/artifact/release.env
```

升级时把 artifact 解压到临时目录。脚本使用 `set -euo pipefail`，严格拒绝额外、
重复或缺失字段，从不执行或 `source` manifest；Compose 同时读取生产 `.env` 和
已验证的候选 manifest。候选只有在全部 readiness 成功后才原子提升为
`.release/current.env`，旧 current 才成为 previous：

```bash
./infra/docker/release.sh upgrade /path/to/artifact/release.env
```

脚本先更新兼容前端并暂停。确认章节切换成功返回
`PUT /api/progress/:novelId`，设置状态在旧后端上明确显示暂不可用，且聊天请求携带
UUID v4 `Idempotency-Key` 后，输入脚本
显示的代码 SHA；随后才会执行迁移和后端更新。旧标签页会收到
`426 client_upgrade_required`，不会以请求体中的过期章节启动 LLM。新 Agent 只在
同一事务写入一对消息并完成 turn；`done` 是数据库提交确认。

升级中途失败时 current/previous 不会被覆盖。恢复最后成功的 current：

```bash
./infra/docker/release.sh restore
```

成功上线后若需回滚，数据库 migration 保持前向兼容且不执行 down migration；脚本
部署 previous，通过 readiness 后再交换 current/previous：

```bash
./infra/docker/release.sh rollback <previous-release-git-sha>
```

回滚到本最小启动决策之前的 release 会在替换任何服务前拒绝，除非：
`CACHE_MODE=redis`、Redis 密码能认证健康容器；并且有有效的 LLM 环境覆盖，
或仍运行且未使用环境覆盖的当前 User Service 能以内部身份访问既有运行时 LLM
端点。守卫只检查 HTTP 状态并丢弃响应体，不读取或输出密钥/密文。

---

## 服务端口说明

| 服务 | 内部端口 | 对外暴露 | 说明 |
|---|---|---|---|
| nginx | 80 | ✅ 80 | 反向代理入口 |
| gateway | 8080 | ❌ 默认关闭（可选 8080） | API 网关 |
| user-service | 8001 | ❌ 内部 | 用户认证 |
| novel-service | 8002 | ❌ 内部 | 小说解析 |
| agent-service | 8003 | ❌ 内部 | 角色对话 |
| narrative-service | 8004 | ❌ 内部 | 分支叙事 |
| postgres | 5432 | ❌ 默认关闭（可选 5432） | 数据库 |
| redis | 6379 | ❌ 默认不启动（`redis` profile） | 可选重建投影 |

**生产环境建议**：关闭 postgres 和 redis 的对外端口映射，仅通过内部网络访问。

---

## API 契约

部署文档不重复维护接口清单。当前规范见 [SPEC §10](./SPEC.md#10-api-contract)，
当前支持范围见 [PRODUCT_CONTRACT.md](./docs/PRODUCT_CONTRACT.md)。

---

## 可选的告警通知

已有监控使用 `docker-compose.monitoring.yml`。需要通知时，再叠加
`docker-compose.alerting.yml`。默认启动方式不要求配置或部署 Alertmanager。
把 `infra/monitoring/alertmanager.example.yml` 复制到仓库外的私有目录，
将示例 URL 换成已授权、支持 Alertmanager webhook 格式的 HTTPS 接收端。
目录权限保持 `0700`，文件须能被容器的 `nobody` 用户读取；私有目录内
的 `0644` 文件可通过只读单文件挂载读取。把绝对路径写入 `.env` 的
`ALERTMANAGER_CONFIG_FILE`。接收端密钥留在这个私有文件中。

先用 `amtool check-config` 验证，再启动通知。命令、超时与重试规则、
接收端去重责任和停用方法见 [告警通知操作说明](./docs/OPERATIONS.md#optional-operator-notifications)。
保留 `alertmanager_data` 卷才能保留通知记录和静默规则。不要用删除数据卷
来停用通知。Alertmanager 只与 Prometheus 共用专用桥接网络，不接入应用网络，
也不发布主机端口。该组件不代表真实值班接收或 SLO 已验收。

## LLM 指标与发布预算

`user-service`、`novel-service`、`agent-service` 和 `narrative-service`
在各自的内部端口暴露 `/metrics`。公网 Nginx 对 `/metrics` 返回 404；由
内部 Prometheus 网络直接抓取服务端口。

指标按受控的 `service/provider/model/operation/mode/status` 标签记录逻辑
请求、实际 provider 尝试、重试、延迟、首 token、usage 缺失、输入/输出/
缓存命中 token，以及 cached-input/uncached-input/output 计费 token。指标不
包含 prompt、URL、错误正文、用户或小说标识。设置页按当前 Key 从 Prometheus
查询近 30 天增量，以随构建发布、带官网来源和核验日期的价格快照重估已报告
计费类别。中国区人民币、国际区美元分别计算，无需汇率；峰谷/上下文/思考
档位缺少逐次信息时显示区间。未知单价不视为免费；Coding/Token Plan 单列
套餐月费报价，不由累计 token 推算实付费用或剩余额度。

`LLM_PRICING_USD_PER_MILLION` 和 `LLM_PRICING_CNY_PER_MILLION` 可显式覆盖
普通 API 的精确 provider/model 单价，同键冲突或套餐 token 单价使启动失败。
`USD_CNY_RATE` 仅用于旧版点估算字段的可选换算。报价核验、更新流程、未统计
费用和回滚边界见 [LLM 计费估算](./docs/LLM_PRICING.md)。这些设置不改变冻结
Diagnostic 的价格、预算或证据。

H3 发布样本使用版本化策略校验：

```bash
python3 tools/llm-budget/verify.py \
  --policy tools/llm-budget/policy-v2.json \
  --metrics release-sample.prom \
  --commit "$(git rev-parse HEAD)"
```

样本必须来自一个完成的、有边界的发布测试窗口；进程重启会重置计数器。
`h3-llm-budget-v2` 使用 3 个 30 分钟 summary 分桶，使任一样本至少保留 60 分钟
（最多 90 分钟），覆盖 45 分钟发布任务上限；
若已启动 operation 的 output-token-limit 窗口为空，校验器会失败而不是把零当作优秀结果。
校验器会拒绝缺服务、缺 operation、usage 缺失、未完成请求、未知/敏感标签、
超出重试/错误/延迟/首 token/计费 token 预算或 provider 实际 token 上限的样本。

---

## 常见问题

**Q: Rust 编译太慢怎么办？**

A: 首次编译需要 5-15 分钟，后续增量编译很快。可以预先拉取 Rust 镜像：
```bash
docker pull rust:1.82-slim-bookworm
```

**Q: 如何更换 LLM 提供商？**

A: 创建首位管理员后，可在受保护的设置页选择 DeepSeek 或 OpenAI。高级部署
可在启动前设置 `.env` 中的 `LLM_API_URL`、`LLM_API_KEY` 和 `LLM_MODEL`，
然后重新运行启动器；环境配置优先于数据库设置并在网页中只读显示。

**Q: 如何启用 Laya (Jev) 行动建议和 D20 裁定？**

A: 两者共用可选的 Laya (Jev) decision 服务，但用途不同：行动建议只分类
玩家显式请求的动作类型；配置成对的 `LAYA_API_URL` 与 `LAYA_API_KEY` 后，
高级 D20 回合还会发送受限的行动/角色上下文进行可行性与难度分类。该上下文
不含小说全文、历史、骰子或结果，仍可能包含玩家背景、能力、库存和目标显示名；
服务商的数据保留由其策略决定。裁定错误、低置信度或上下文超限会回退到模板
DC，服务器校验和骰子仍是权威，语义质量尚未认证。它不替代 DeepSeek 故事生成。
优先复用现有且可从两个容器访问的私有/共享 Laya；正常源码启动和 Jenkins 部署
不会提供或启动 Laya。只有明确需要独立实例时，才叠加 `docker-compose.laya.yml`
并运行下方的 `--profile laya` 命令。
让 Laya 服务与
`novel-service`、`narrative-service` 处于同一条私有 Docker 网络，在 `.env` 中填写
`LAYA_API_URL=http://<Laya容器名>:8000` 和 `LAYA_API_KEY`，然后重建并重启 Novel 与 Narrative，以启用 D20 裁定和系列匹配。地址必须分别从
Novel 和 Narrative 容器内可达；宿主机的
`127.0.0.1:18881` 在容器内指向 Narrative 自己。只使用私有网络，
不要公开 Novel、Narrative 或 Laya 端口。未同时配置 URL 和密钥时，行动
建议入口隐藏，系列识别返回未配置并保留手动关联。系列推荐需用户确认；
Laya 失效时仍可手动选择系列或行动，高级检定回退到模板 DC。系列绑定需要
匹配的 Novel、Narrative 和前端版本；0031 和 0033 经正常受管停机迁移执行，且不新增
发布屏障。0033 允许先创建仅共享背景的系列；D20 规则由用户以后显式生成，
来源书的就绪规则只会固定一次。来源规则未就绪时，系列成员不能用各自的规则
代替。绑定状态产生后，旧版本回滚不受支持。

**Q: 如何显式运行或升级 NovelWorld 独立 Laya？**

A: 仅在需要独立实例时，显式叠加 `docker-compose.laya.yml`，使用包含 `laya==0.3.20` 和已审查的
multilingual checkpoint 的不可变镜像。在根 `.env` 设置 `LAYA_IMAGE` 为镜像
digest（本机测试也可用精确 image ID）、`LAYA_MODEL_PATH` 为镜像内固定 revision
的本地 checkpoint 路径、`LAYA_API_URL=http://laya:8000`，保持既有密钥。先验证
镜像包版本、checkpoint 内容和权限；不要使用浮动 `latest`。该 endpoint 不下载
模型，不发布宿主机端口，只加载 multilingual，限制 CPU/内存/线程，并对会截断
state 的请求返回 422；问题头部和选项仍使用上游 token 预算。升级不会自动提升
识别准确率或改变 0.8 弃权阈值。

```bash
docker compose -f docker-compose.yml -f docker-compose.laya.yml --profile laya up -d laya
```

验证健康、鉴权以及系列/行动/D20 协议兼容后，按正常部署流程更新 Novel 与
Narrative 的 URL；保留原共享服务和其他消费者。回滚只恢复这两个消费者原来的
URL 并重建，随后可停止本项目独立 Laya。不要删除共享模型缓存或其他项目容器。

系列识别只调用已配置的 Laya 服务。用户可主动点击 DeepSeek 补判，使用设置页当前
配置的 DeepSeek API 与现有计费路径；其他 provider 或 Diagnostic 绑定会被拒绝。
相同证据/候选/策略/模型复用 PostgreSQL 结果。每条 claim 最多一次实际请求，输出上限为 512 tokens（启用思考时包含思考 tokens），
不做 HTTP 重试、JSON fallback 或修复重发；未知结果也不自动重试。“查询结果”使用只读的 `check_only=true` 模式；证据或
模型配置改变时，也不会把查询变成新的付费请求。0032 缓存迁移
必须先于新版 Novel 启动，缓存不会改已有系列或 D20 绑定。本功能测试和部署不
构成执行新的付费 Diagnostic 的授权。

**Q: pgvector 扩展安装失败？**

A: pgvector 是当前 schema 的必需扩展。不要修改 `init.sql` 绕过它；修复镜像或扩展
安装后重新执行迁移。项目目前不承诺无 pgvector 的生产降级模式。

**Q: 如何备份数据库？**

```bash
docker exec novel-postgres pg_dump -U novel novel_world > backup_$(date +%Y%m%d).sql
```

以上示例未加密、未做完整性校验，也未经恢复演练验证。已批准的恢复目标
（RPO/RTO）、加密与完整性要求、保留上限和擦除重放契约见
[`docs/BACKUP_RESTORE.md`](docs/BACKUP_RESTORE.md)；配套的脚本化备份/恢复
工具随该政策的实现变更交付。

---

## 私有部署安全基线

1. **网络**：保持在 localhost；非本机访问使用管理员维护的加密隧道或 TLS，且不要
   把默认 Nginx 直接暴露到公网。
2. **端口**：只开放私网入口，关闭 5432/6379/8080 的外部映射。
3. **密钥**：使用启动脚本生成的随机值并限制 `.env` 文件权限。
4. **备份**：制定并演练 PostgreSQL、S3 和操作员日志的恢复与删除策略；示例
   `pg_dump` 命令不是已验证的 RPO/RTO。
5. **监控**：从内部网络抓取各服务 `/metrics`；Nginx 继续对公网路径返回 404。

公网托管需要 H2 的独立安全、隐私、内容、滥用、供应链、TLS/CORS 和恢复审查；
上述基线不能替代该资格门槛。

### Community series suggestions (migration 0035)

Apply additive migration 0035 before starting the matching Novel/frontend pair;
normal managed migrations and desktop startup include it. Existing series do
not contribute until their owner opts in. No provider credential or additional
configuration is needed. Rolling back the frontend/API keeps the additive table
and all prior private backgrounds, rules and frozen sessions intact; no down
migration is required. See [ADR 0012](docs/adr/0012-opt-in-community-series.md).