运行时配置与品牌定制¶

1. 配置分类¶

PE Agent 前端将配置分为：

浏览器可见的运行时配置；
Next.js 服务端私密配置；
Docker Compose 和部署流水线变量。

不要因为变量写在 .env 中就默认它是秘密。被注入 window.__RUNTIME_CONFIG__ 的值，浏览器用户都能查看。

2. 浏览器可见运行时配置¶

以下名称由当前前端运行时配置机制读取：

分组	变量名
路径与静态资源	`APP_BASE_PATH`、`STATIC_BASE_URL`
品牌	`BRAND_NAME`、`BRAND_LOGO_PATH`、`BRAND_FAVICON_PATH`
外部前端服务	`SANDPACK_BUNDLER_URL`、`ONLYOFFICE_URL`
显示与诊断	`DEBUG`、`ANNOUNCEMENT`、`ENABLE_VERSION_CHECK`
功能开关	`ENABLE_INVITE_CODE`、`ENABLE_REDEEM_CODE`、`ENABLE_USER_LLM_SETTINGS`、`ENABLE_USER_PASSWORD_CHANGE`、`ENABLE_ADMIN_SECTION`、`ENABLE_VERIFICATION_CODE`、`ENABLE_CLAW`
请求兼容	`ENABLE_HTTP_METHOD_OVERRIDE`
Cookie 策略	`AUTH_COOKIE_ACCESS_TOKEN_KEY`、`AUTH_COOKIE_REFRESH_TOKEN_KEY`、`AUTH_COOKIE_REFRESH_TOKEN_MAX_AGE`、`AUTH_COOKIE_DOMAIN`

浏览器配置由根布局注入，不依赖 NEXT_PUBLIC_* 构建时替换。同一个镜像可以在不同部署环境中通过修改运行时 .env 和重启容器复用。

3. 服务端配置¶

当前 server-only 配置包括：

分组	变量名
应用和 API	`APP_DOMAIN`、`API_SERVER_URL`、`PUBLIC_SITE_ORIGIN`
搜索引擎	`DISABLE_ROBOTS`
ONLYOFFICE	`ONLYOFFICE_JWT_SECRET`、`ONLYOFFICE_ALLOWED_FILE_URL_PREFIXES`
OpenSandbox	`OPEN_SANDBOX_API_URL`、`OPEN_SANDBOX_API_KEY`、`OPEN_SANDBOX_PREVIEW_IMAGE`
站点访问	`BASIC_AUTH_USER`、`BASIC_AUTH_PASS`
历史入口	`PEAGENT_REDIRECT_BASE_URL`

其中 Secret、Key 和密码必须通过受控的密钥管理或配置文件下发，不能写入浏览器配置、Markdown、截图或镜像层。

4. `APP_BASE_PATH`¶

该变量控制前端部署在域名根路径或二级路径。

有效值必须：

为空或以 / 开头；
不以 / 结尾；
不包含连续斜杠、反斜杠、query 或 hash；
不包含 .、.. 路径段。

它会影响：

页面链接和跳转；
/server/* 与 /api/*；
public 资源；
Cookie Path；
ONLYOFFICE 回调；
项目预览路径；
健康检查地址。

修改后需要重启或重新创建容器，但不需要重建镜像。

5. 静态资源¶

STATIC_BASE_URL 为空时，public/static/* 随应用路径提供；配置后可指向项目 CDN 或独立静态站点。

业务代码通过 staticUrl() 生成静态资源地址，避免硬编码 /static/...。

品牌 Logo 和 Favicon 通过 public 资源路径函数处理，不与普通静态资源完全相同。根布局还会加载 public/branding/theme.css。

6. 品牌定制¶

推荐分层处理：

名称、Logo、Favicon：运行时变量；
品牌色和 CSS 变量：public/branding/theme.css；
组件级设计 Token：src/theme/antd-theme.ts；
通用 Tailwind Token：src/styles/globals.css。

Compose 中可以启用只读 volume 挂载品牌文件，从而在不重建镜像的情况下替换项目品牌资源。

品牌配置至少检查：

登录、注册和找回密码；
顶部 Logo；
浏览器标题和 Favicon；
浅色与深色主题；
404、错误页和空状态；
二级路径和静态资源；
高分辨率屏幕清晰度。

7. 功能开关¶

功能	前端开关
注册邀请码	`ENABLE_INVITE_CODE`
兑换口令	`ENABLE_REDEEM_CODE`
用户大模型配置	`ENABLE_USER_LLM_SETTINGS`
用户修改密码	`ENABLE_USER_PASSWORD_CHANGE`
批量账号导入入口	`ENABLE_ADMIN_SECTION`
注册验证码	`ENABLE_VERIFICATION_CODE`
本地工具	`ENABLE_CLAW`

Important

功能开关只控制前端显示和路由行为，不是授权边界。批量导入、模型配置、兑换等接口必须由服务端校验身份和权限。

8. Basic Auth¶

同时配置 BASIC_AUTH_USER 和 BASIC_AUTH_PASS 时，前端代理可以启用站点级 Basic Auth。当前实现对 /api、/server、/static 和 /_next 有豁免，因此 Basic Auth 不能代替后端认证和接口授权。

9. HTTP Method Override¶

启用 ENABLE_HTTP_METHOD_OVERRIDE 后，Axios 的 DELETE、PUT、PATCH 请求会改为 POST，并通过 X-HTTP-Method-Override 表示原始方法。

项目网关和后端必须同时支持该约定。流式 fetch 不参与改写。

10. 配置变更流程¶

在配置模板中记录变量名、作用域、是否必填和保密级别；
通过安全渠道生成目标环境值；
更新容器运行时 .env；
重启或重新创建容器；
检查 /api/health；
验证登录、接口代理、静态资源和可选功能；
不在日志和工单中粘贴完整 .env。