Merge branch 'master' of https://git.genarrative.world/GenarrativeAI/Genarrative

.hermes/shared-memory/decision-log.md

@@ -574,6 +574,14 @@
 - 验证方式：生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 - 关联文档：`PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
+## 2026-05-19 release server provision 需预装 Nginx Brotli 动态模块
+
+- 背景：release 服务器的 Nginx 站点配置已经预留 Brotli 指令占位，但当前 provision 流程只装了基础构建依赖，没有把 Ubuntu apt 下的 brotli 动态模块一起装上，导致 release 机器即使模板支持也可能无法启用 Brotli。
+- 决策：`scripts/jenkins-server-provision.sh` 在 apt 系统上额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，然后继续用会先 `include /etc/nginx/modules-enabled/*.conf` 的临时 `nginx -t` 配置做能力探测；非 apt 系统仍只做探测不强制安装。不要用 `nginx -V` 判断该动态模块是否可用。
+- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、`deploy/nginx/README.md`、release 服务器 Nginx 初始化。
+- 验证方式：server provision 跑过后，目标机应同时具备 Brotli 模块包与 `nginx -t` 可接受的 brotli 指令；再由 Nginx 模板启用对应指令。
+- 关联文档：`deploy/nginx/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 个人任务与埋点首版边界冻结
 
 - 背景：“我的”Tab、任务、奖励、钱包和埋点涉及用户、运营、分析多条链路，需要避免范围泛化。

deploy/nginx/README.md

@@ -11,13 +11,18 @@
 ## Brotli
 
 - Brotli 只在目标服务器 Nginx 接受 brotli 指令时开启。
+- Ubuntu / apt 系统的 `Genarrative-Server-Provision` 会安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`；非 apt 系统暂不自动安装，仍按下面的能力探测结果决定是否启用。
 - Provision 脚本通过临时配置执行 `nginx -t` 做能力探测；探测配置会先 `include /etc/nginx/modules-enabled/*.conf`，避免 Ubuntu 动态模块已安装但测试配置未加载模块导致误判。可用时把模板中的 `# __GENARRATIVE_BROTLI_DIRECTIVES__` 替换为 brotli 指令，不可用时保留注释说明。
 - 不要直接在静态模板里无条件写 `brotli on;`，否则没有 brotli 模块的服务器会 `nginx -t` 失败并回滚。
-- 不要用 `nginx -V | grep brotli` 判断 brotli 是否可用；Ubuntu apt 安装的 brotli 是动态模块，可能只出现在 `nginx -T` 的 `load_module` 配置里。
+- 不要用 `nginx -V | grep brotli` 判断 brotli 是否可用；Ubuntu apt 安装的 brotli 是动态模块，不会出现在普通编译参数里。应检查包、`/etc/nginx/modules-enabled/` 的 `load_module` 配置，或用包含 `include /etc/nginx/modules-enabled/*.conf` 的临时配置执行 `nginx -t`。
 
 ## 验证
 
 ```bash
+dpkg -l 'libnginx-mod-http-brotli-*'
+ls -l /etc/nginx/modules-enabled/*brotli*
+nginx -T 2>/dev/null | grep -Ei 'brotli|load_module'
+
 curl -sSI -H 'Accept-Encoding: gzip' \
   http://<host>/api/runtime/puzzle/gallery \
   | grep -iE 'content-encoding|vary|content-type|content-length'

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -153,6 +153,8 @@ Windows Stdb module 构建流水线运行在 Jenkins `windows` 节点上。该
 
 生产环境变量模板：`deploy/env/api-server.env.example`。真实密钥只放服务器，不提交 Git，不写入文档示例。
 
+`Genarrative-Server-Provision` 会安装基础构建依赖、systemd 模板和 Nginx 站点模板。Ubuntu / apt 目标机会额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，随后由 `scripts/jenkins-server-provision.sh` 通过临时 `nginx -t` 配置探测 Brotli 指令是否可用；该临时配置必须先 `include /etc/nginx/modules-enabled/*.conf`，因为 apt 安装的 Brotli 是动态模块，不会出现在普通 `nginx -V` 编译参数里。探测成功才在渲染后的 `deploy/nginx/genarrative.conf` / `genarrative-dev-http.conf` 中启用 Brotli，避免未安装模块的机器直接写入无效配置。
+
 50 HTTP req/s 首版压测优化口径：
 
 - `api-server` 生产模板默认 `GENARRATIVE_API_LISTEN_BACKLOG=1024`、`GENARRATIVE_API_WORKER_THREADS=4`；本地未设置 worker threads 时继续使用 Tokio 默认值。

scripts/jenkins-server-provision.sh

@@ -63,6 +63,15 @@ install_build_dependencies() {
   fi
 }
 
+install_nginx_brotli_modules() {
+  echo "[server-provision] 安装 Nginx Brotli 动态模块依赖"
+  if command -v apt-get >/dev/null 2>&1; then
+    run_cmd apt-get install -y libnginx-mod-http-brotli-filter libnginx-mod-http-brotli-static
+  else
+    echo "[server-provision] 当前系统未使用 apt，无法自动安装 Nginx Brotli 动态模块；将继续通过 nginx -t 能力探测决定是否启用 Brotli。"
+  fi
+}
+
 install_sccache() {
   for tool_dir in "${HOME:-}/.cargo/bin" /root/.cargo/bin /usr/local/cargo/bin; do
     if [[ -d "${tool_dir}" && ":${PATH}:" != *":${tool_dir}:"* ]]; then
@@ -537,6 +546,7 @@ echo "[server-provision] target=${DEPLOY_TARGET}, dry_run=${DRY_RUN}, nginx_conf
 
 run_cmd id
 install_build_dependencies
+install_nginx_brotli_modules
 install_sccache
 run_cmd mkdir -p "${SPACETIME_ROOT}" "${RELEASE_ROOT}" "$(dirname "${CURRENT_LINK}")" "$(dirname "${WEB_LINK}")" /etc/genarrative /var/lib/genarrative/maintenance /var/lib/genarrative/auth