这页不只是环境变量清单，而是帮你先决定三件事：
| 关注点 | 关键变量 | 默认值 | 什么时候该改 |
|---|---|---|---|
| 应用监听地址 | HTTP_BIND |
本地默认 127.0.0.1:8080；运行镜像默认 0.0.0.0:8080 |
本地开发、容器部署或反向代理拓扑不同时 |
| 数据库存放位置 | DATABASE_PATH |
codex_vibe_monitor.db |
想把 SQLite 和归档放到持久化卷时 |
| 维护状态库 | MAINTENANCE_DATABASE_PATH |
主库同目录的 .maintenance.sqlite |
想把任务状态库单独放置时 |
| 原始 payload | PROXY_RAW_DIR |
proxy_raw_payloads |
想把代理 request/response 文件放到独立持久化卷时 |
| 离线归档 | ARCHIVE_DIR |
archives |
想把历史归档文件放到独立持久化卷时 |
| Xray runtime | XRAY_RUNTIME_DIR |
.codex/xray-forward（相对进程工作目录） |
想调整 Xray 状态与配置目录时 |
| 性能观测 | OBSERVABILITY_ENABLED |
true |
A/B 或故障时关闭观测，不影响业务 |
| 指标私网监听 | METRICS_BIND、METRICS_TOKEN_FILE |
127.0.0.1:9091 |
容器用监控私网，非 loopback 必须配 Token 文件 |
| 诊断与图表 | OBSERVABILITY_READ_TOKEN_FILE、GRAFANA_PUBLIC_URL |
无 | 配置独立只读诊断 Token 和 Grafana HTTPS 入口 |
| 上游代理目标 | OPENAI_UPSTREAM_BASE_URL |
OpenAI 官方默认地址 | 你接的是自建兼容上游或其他转发层时 |
| 账号池写能力 | UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET |
无 | 只要你要新增账号、改账号或用 OAuth 登录，就必须配置 |
| 数据保留与归档 | 任务页自动触发开关、ARCHIVE_DIR、各类 retention 天数 |
四项维护任务默认自动启用，可独立暂停 | 想长期运行并控制主库体积时 |
如果你只是先把服务跑起来，通常先确认上表这 4 到 5 项就够了。
HTTP_BIND、DATABASE_PATH 基本就会先决定。OPENAI_UPSTREAM_BASE_URL。UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET。ARCHIVE_DIR 和各类 retention 窗口。UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET：启用号池写入与加密落库的必填密钥UPSTREAM_ACCOUNTS_OAUTH_CLIENT_IDUPSTREAM_ACCOUNTS_OAUTH_ISSUERUPSTREAM_ACCOUNTS_USAGE_BASE_URLUPSTREAM_ACCOUNTS_LOGIN_SESSION_TTL_SECSUPSTREAM_ACCOUNTS_SYNC_INTERVAL_SECSUPSTREAM_ACCOUNTS_REFRESH_LEAD_TIME_SECSUPSTREAM_ACCOUNTS_HISTORY_RETENTION_DAYS如果你不打算启用 Account Pool 的写入能力，这一组可以后置。
如果你准备让 OAuth 账号真正上线，不要把这组变量拖到最后才补。
RETENTION_DRY_RUNRETENTION_INTERVAL_SECSRETENTION_BATCH_ROWSARCHIVE_DIRINVOCATION_SUCCESS_FULL_DAYSINVOCATION_MAX_DAYSFORWARD_PROXY_ATTEMPTS_RETENTION_DAYSSTATS_SOURCE_SNAPSHOTS_RETENTION_DAYSQUOTA_SNAPSHOT_FULL_DAYS这些参数控制在线明细、离线 archive 与后台 maintenance 行为。
如果你希望数据库体积可控、raw 文件不无限增长、归档路径能备份，就不要只停在“默认值也能跑”这个阶段。
项目状态页的项目存储总体积会扫描 DATABASE_PATH 父目录，并纳入单独配置的外置存储。PROXY_RAW_DIR 保存代理 request/response payload，ARCHIVE_DIR 保存离线归档；二者相对路径都以主库父目录为锚点，使用绝对路径可以放到不同卷。目录在数据目录内时会自然包含在主目录扫描中，外置时会完整统计该目录，包括临时文件和未关联残留。外置的维护库只计数据库文件及 WAL/SHM/journal 侧文件，不会把同级无关文件纳入。所有路径最后按文件系统对象去重，因此重叠目录、别名和硬链接不会重复计入。
要把 raw 与离线归档分别放到独立持久卷，可向服务进程传入绝对路径：
PROXY_RAW_DIR 用于代理 request/response 原始文件，ARCHIVE_DIR 用于离线归档；容器部署时还需把对应宿主机目录挂载到这些容器内路径。省略变量时分别使用 proxy_raw_payloads 和 archives，相对路径仍以主库父目录为基准。
OPENAI_UPSTREAM_BASE_URL：OpenAI 兼容上游基址REQUEST_TIMEOUT_SECS：通用请求超时OPENAI_PROXY_HANDSHAKE_TIMEOUT_SECS：非 compact 路径的上游握手超时OPENAI_PROXY_COMPACT_HANDSHAKE_TIMEOUT_SECS：/v1/responses/compact 上游握手超时OPENAI_PROXY_IMAGE_HANDSHAKE_TIMEOUT_SECS：/v1/images/generations 与 /v1/images/edits 等待上游首字节的默认超时，默认 300 秒；运行时可由四层 timeout 策略覆盖OPENAI_PROXY_REQUEST_READ_TIMEOUT_SECS：请求体读取总超时OPENAI_PROXY_ENCRYPTED_SESSION_OWNER_ROUTING_ENABLED：加密对话路由绑定的首次初始化默认值；默认关闭，只有数据库里该设置还没初始化时才会吃 envOPENAI_PROXY_MAX_REQUEST_BODY_BYTES：请求体最大尺寸限制PROXY_RAW_DIR / PROXY_RAW_MAX_BYTES / PROXY_RAW_COMPRESSION / PROXY_RAW_HOT_SECS：原始 payload 落盘、热保留与冷压缩策略PROXY_ENFORCE_STREAM_INCLUDE_USAGE：是否在流式请求中强制补 include_usagePROXY_USAGE_BACKFILL_ON_STARTUP：历史补数兼容开关FORWARD_PROXY_ALGO：forward proxy 权重算法版本VITE_BACKEND_PROXY：前端开发服务器代理目标，默认 http://localhost:8080VITE_APP_RUNTIME：应用运行时，值只能是 live 或 demo；demo 只使用浏览器内存与 MSW mock，不回退到真实 APIVITE_DEPLOY_BASE：静态资源与 MSW worker 的部署基路径；GitHub Pages demo 使用 ${DOCS_BASE}demo/VITE_APP_PORT：Vite app/demo 的监听端口；demo 默认 60083，实际开发应使用 worktree 租约端口DOCS_PORT：docs-site 本地 dev/preview 端口，默认 60081DOCS_BASE：静态站部署基路径；GitHub Pages 项目页通常使用 /<repo>/VITE_STORYBOOK_DEV_ORIGIN：docs-site 本地 storybook.html 跳转到 Storybook dev server 时使用的完整 origin；默认 http://127.0.0.1:60082STORYBOOK_PORT：Storybook 本地开发端口，默认 600826008060083（开发时使用租约端口覆盖）60081600828080这些端口都允许通过 env 或命令行覆盖，但文档、脚本与 CI 默认按以上合同组织。
本地运行时建议把个人配置写入 .env.local。服务启动会以仓库根目录下的当前环境变量与 .env.local 为准。