From 28a57cbde50a2f0dd216346651f39dfbce6978d3 Mon Sep 17 00:00:00 2001 From: Zyy Date: Mon, 5 Oct 2026 09:44:32 +0800 Subject: [PATCH] feat(deploy): add opt-in low-memory allocator configuration Keep the glibc tuning value in config.yaml's app-runtime bridge and let Compose inject it before the application starts. Leave tuning disabled by default and document the 128 KiB preset, recreation, and upgrade steps. Refs #338, #345 Co-authored-by: Codex --- deploy/README.md | 45 +++++++++++++++++++++++++++++++++++--- deploy/compose.yaml | 3 +++ deploy/config.example.yaml | 9 +++++++- 3 files changed, 53 insertions(+), 4 deletions(-) diff --git a/deploy/README.md b/deploy/README.md index afc65871c..974d14cb3 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -8,7 +8,7 @@ | --- | --- | | 安装与启动 | [手动安装](#手动安装) · [启动](#启动) · [公网访问](#公网访问) | | 接入客户端 | [客户端配置](#客户端配置) · [登录与生图排查](#登录与生图排查) | -| 日常运维 | [运行设置](#启动后的运行设置) · [持久化与日志](#持久化与备份) · [请求排查](#请求错误排查) · [密码轮换](#密码语义) | +| 日常运维 | [运行设置](#启动后的运行设置) · [小内存优化](#小内存优化) · [持久化与日志](#持久化与备份) · [请求排查](#请求错误排查) · [密码轮换](#密码语义) | | 更新与恢复 | [镜像升级](#镜像升级与源码构建) · [在线更新](#管理端在线更新) · [备份与恢复](#备份与恢复) · [优雅关停](#优雅关停) | | 运行源码 | [开发与源码联调](../docs/development.md) | @@ -18,12 +18,13 @@ | 位置 | 内容 | 修改方式 | | --- | --- | --- | -| `deploy/config.yaml` | 监听、数据库/Redis 连接、部署凭据、时区与日志等启动配置 | 从模板创建，已有部署合并修改，不覆盖原文件 | +| `deploy/config.yaml` | 监听、数据库/Redis 连接、部署凭据、时区、日志与可选内存分配策略等启动配置 | 从模板创建，已有部署合并修改，不覆盖原文件 | | `deploy/compose.yaml` | 镜像、容器网络、端口、挂载与资源限制 | 调整 Compose 并重建受影响容器 | | PostgreSQL | 账号、Key、运行设置、上游身份、插件配置等业务数据 | 管理端或管理 API | | 浏览器本地 | 主题和界面偏好 | 当前浏览器的主题设置 | -项目不使用 `.env` 配置文件。Compose 环境变量用于容器地址、镜像选择和构建发布。 +项目不使用 `.env` 配置文件。Compose 环境变量用于容器地址、镜像选择和构建发布； +可选的内存分配策略由 `config.yaml` 的 `services.app-runtime` 桥接到应用容器。 配置加载会忽略未知字段，并在启动控制台提示字段名；不输出对应值。缺少必填字段时会指出缺项并停止启动， 已知字段的类型和取值仍需合法；可选字段省略时使用默认值 @@ -51,6 +52,44 @@ host: 备份调度从切换后的当前时刻计算未来执行点，不补跑旧时区漏过的任务，已入队任务保持原状态。 夏令时中不存在的预热或 Cron 时刻跳过，重复时刻只选较早一次。日志日期与保留规则见[日志与保留窗口](#日志与保留窗口) +### 小内存优化 + +Linux/glibc 部署可选择更积极地归还请求结束后的空闲内存，适合内存紧张且请求后 RSS 长时间偏高的机器。 +该选项默认关闭，官方 Linux 镜像支持；更频繁的映射与回收可能增加 CPU 开销，应结合实际负载观察 + +在 `deploy/config.yaml` 的 `services.app-runtime.environment` 中设置 `GLIBC_TUNABLES`，空字符串表示不启用额外调优： + +```yaml +services: + app-runtime: + environment: + GLIBC_TUNABLES: 'glibc.malloc.mmap_threshold=131072:glibc.malloc.trim_threshold=131072' +``` + +已有部署使用当前 Compose 模板时，需将 `config.example.yaml` 的 `app-runtime` 段合并到现有 `services` 下，保留 PostgreSQL 和 Redis 的桥接配置。 +即使不开启优化，也保留该段并将值设为 `''`；Compose 从这里取得参数，无需在 `compose.yaml` 重复填写 + +校验并重建应用容器使配置生效；`docker compose restart` 不会更新容器环境变量： + +```bash +docker compose -f deploy/compose.yaml config --quiet +docker compose -f deploy/compose.yaml up -d --no-build --no-deps --force-recreate codex-proxy-rs +``` + +此配置将 glibc 的 mmap 与 trim 阈值固定为 128 KiB，关闭对应的动态阈值调整。 +如已有 `GLIBC_TUNABLES`，用冒号合并这两个参数，避免重复同名项；同时检查是否另设了 `MALLOC_MMAP_THRESHOLD_` 或 `MALLOC_TRIM_THRESHOLD_`，统一在一处维护。 +参数含义见 [glibc 文档](https://sourceware.org/glibc/manual/latest/html_node/Memory-Allocation-Tunables.html) + +关闭时删除这两个参数；没有其他 tunable 时将值恢复为 `''`，然后再次重建应用容器。 +`services` 是 Compose 桥接区，直接运行二进制不会读取这一段。Linux/glibc 二进制部署需由启动器在进程启动前设置同一环境变量，例如： + +```bash +GLIBC_TUNABLES=glibc.malloc.mmap_threshold=131072:glibc.malloc.trim_threshold=131072 ./codex-proxy-rs +``` + +该变量由 glibc 在进程启动时读取，不支持管理端热更新。 +它不设置内存上限，不释放仍被请求或连接持有的缓冲，也不处理容器文件缓存；观察时分别比较进程 RSS、cgroup 的 `anon` 与 `file` + ## 部署结构 ```mermaid diff --git a/deploy/compose.yaml b/deploy/compose.yaml index 2a6169ca8..be0e965af 100644 --- a/deploy/compose.yaml +++ b/deploy/compose.yaml @@ -64,6 +64,9 @@ services: logging: *json-logging codex-proxy-rs: + extends: + file: config.yaml + service: app-runtime image: ${CPR_IMAGE:-ghcr.io/zyycn/codex-proxy-rs:latest} build: context: .. diff --git a/deploy/config.example.yaml b/deploy/config.example.yaml index f02bbd511..6fbc05695 100644 --- a/deploy/config.example.yaml +++ b/deploy/config.example.yaml @@ -76,8 +76,15 @@ openai: # 数据驻留约束；省略或 null 不指定地域约束，与管理端客户端身份无关。 residency: us -# Compose 凭据桥接区；密码仍只维护在 store 中。 +# Compose 启动桥接区；密码仍只维护在 store 中。 services: + app-runtime: + environment: + # 默认空值；小内存机器可改为下列值，更积极回收空闲内存，但可能增加 CPU 开销。 + # 'glibc.malloc.mmap_threshold=131072:glibc.malloc.trim_threshold=131072' + # 由 Compose 在进程启动前传入，修改后需重建应用容器，详见 deploy/README.md#小内存优化。 + GLIBC_TUNABLES: '' + postgres-credentials: environment: POSTGRES_PASSWORD: *postgres_password