# 配置参考

Raise 系统完全通过环境变量进行配置。在生产环境（`KWORK_ENV` 不是 `dev`）中，若缺少必填配置项，服务会拒绝启动并列出缺失项。在 Docker Compose 部署中，`deploy/compose/.env` 配置文件由安装脚本生成，启动时还会叠加 `versions.env` 与 `packs/{pack}.env`。

## 谁能用

- **部署方与运维人员**：负责编辑 `deploy/compose/.env`（文件权限设为 600）或修改 Helm 的 `values.yaml` 与 Secret。
- **租户管理员**：负责在工作台打开「我的组织」，管理租户内部策略（模型、存储、域名），不修改这些系统环境变量。
- **环境隔离限制**：`KWORK_ENV=dev` 允许使用内存存储与临时密钥，**不得用于任何对外环境**。

## 怎么打开

系统配置无图形操作界面，通过以下文件与命令行入口进行管理：

- **配置文件**：
  - `deploy/compose/.env`
  - `deploy/compose/.env.example`
  - `deploy/packs/*.env`
  - `deploy/versions.env`
- **维护命令**：
  - `kwork serve`（默认启动服务命令）
  - `kwork migrate`（执行数据库迁移）
  - `kwork bootstrap zitadel|openbao|s3`（执行依赖组件初始化引导）
  - `kwork healthcheck`（检查服务健康状态）
  - `kwork version`（查看程序版本）
- **Helm 部署入口**：
  - 在 `values.yaml` 中通过 `kwork.extraEnv` 可注入任意 `KWORK_*` 环境变量。

## 界面一览

系统没有提供图形化配置界面：

- **运营台「服务导航」**：进入[运营台](/ops/)的「服务导航」，可以查看各已部署组件的运行状态与健康信息。
- **容器配置文件重启**：修改了由容器启动时读取的文件（`otelcol.yaml`、`prometheus.yml`）后，需要执行以下命令重启容器：
  ```bash
  docker compose restart otel-collector prometheus
  ```
  重新运行 `install.sh` 安装脚本也会自动重启它们。
- **网关配置重载**：修改网关的 Caddyfile 配置文件后，执行以下命令重载配置：
  ```bash
  caddy reload
  ```

## 常用操作

### 查看与修改配置

1. 登录服务器终端，进入 `deploy/compose` 目录。
2. 编辑 `.env` 文件（或对应环境包的 `packs/{pack}.env` 文件）。注意不要把真实 `.env` 文件提交进 git 版本库。
3. 执行以下命令重启服务，使运行中的容器读取新配置：
   ```bash
   docker compose --env-file ../versions.env --env-file ../packs/{pack}.env --env-file .env up -d
   ```
   在 Helm 部署中，修改了 Secret 或配置校验和的 Pod 会自动滚动重启。
4. 若生产环境缺少必填配置项，服务启动将失败，终端会列出缺失项并提示由 `install.sh` 生成密钥。

### 执行系统维护命令

你可以在终端中执行以下维护命令：

- **启动主服务**：
  ```bash
  kwork serve
  ```
- **执行数据库迁移**：
  ```bash
  kwork migrate
  ```
  执行迁移命令时必须提供 `KWORK_MIGRATE_DATABASE_URL` 变量。
- **执行组件初始化引导**：
  ```bash
  kwork bootstrap zitadel
  kwork bootstrap openbao
  kwork bootstrap s3
  ```
- **检查服务健康状态**：
  ```bash
  kwork healthcheck
  ```
- **查看当前程序版本**：
  ```bash
  kwork version
  ```

### 运行与拓扑配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_ENV` | 运行环境标识，可选值为 `dev` 或 `prod`。非 `dev` 即按生产环境规则校验。 | `dev` | 生产环境应设为 `prod`（`single` 环境包已预置） |
| `KWORK_MODULES` | 启用的功能模块列表，可选值为 `app-api`、`k3-control`、`worker`、`agent-runtime`。 | `app-api,k3-control` | 否（Compose 环境通常增加 `worker`） |
| `KWORK_ADDR` | 公网业务监听地址。 | `:8000` | 否 |
| `KWORK_OPS_ADDR` | 运营后台服务监听地址。 | `:8010` | 否 |
| `KWORK_INTERNAL_ADDR` | 内部接口监听地址（用于证书批准、就绪与存活探针、指标采集等内部端点）。 | `:8009` | 否 |
| `KWORK_BASE_DOMAIN` | 门户基础域名。 | 空 | 生产环境必填 |
| `KWORK_PUBLIC_URL` | 工作台公网访问地址及令牌断言签发者（`iss`）。 | `http://localhost:8000` | 否（Compose 常见值为 `https://app.$BASE_DOMAIN`） |
| `KWORK_SITES_HOST` | 独立站点 CNAME 解析目标主机。 | 空（生效为 `sites.{base}`） | 否 |
| `KWORK_DOCS_URL` | 本手册的地址。组织管理里接入设置页的「接入指南」链接指向这里；填 `off` 则不显示这些链接。 | 空（生效为 `https://docs.{base}`） | 否 |
| `KWORK_SITE_DOMAIN_CAP` | 单个组织绑定的站点域名数量上限。 | `10` | 否 |
| `KWORK_TLS_ASK_PER_HOST` | 单台主机在每个时间窗口内允许的证书批准申请次数。设为 `-1` 表示不限制。 | `6` | 否 |
| `KWORK_TLS_ASK_GLOBAL` | 全租户加预览环境合计证书批准申请次数上限。 | `300` | 否 |
| `KWORK_TLS_ASK_WINDOW_MIN` | 证书批准频次限制的时间窗口长度（分钟）。 | `60` | 否 |
| `KWORK_LICENSE_FILE` | 商业许可授权文件路径。未设置时系统作为 Community 社区版运行。 | 空 | 否 |
| `KWORK_LICENSE_PUBKEY` | 厂商公钥（base64 编码）。 | 空（构建时写入） | 否 |
| `KWORK_LICENSE_UNSIGNED` | 是否跳过许可签名校验。设为 `true` 时不校验签名。 | `false` | 仅开发环境使用 |
| `KWORK_BRAND_FILE` | 实例品牌配置文件路径。 | `brand/default/brand.json` | 否（Compose 挂载至 `/etc/kwork/brand/brand.json`） |
| `KWORK_TENANT_BRAND_DIR` | 静态租户品牌配置目录。 | 空（生产走数据库） | 否 |
| `KWORK_LOG_LEVEL` | 日志输出级别。仅当设为 `debug` 时打开调试日志。 | 未设则非 debug | 否 |
| `KWORK_DOWNLOADS_DIR` | k3 构建工件下载目录。 | `/usr/share/kwork/dl` | 否 |
| `KWORK_OPS_PORT` | 服务导航中展示的运营后台访问端口。 | `8443` | 否 |
| `KWORK_SERVICE_PROBES` | 覆盖探针 URL 的 JSON 字符串。 | 空 | 否 |
| `KWORK_REMOTE_APPS` | 独立进程运行的一方应用映射列表，格式为 `id=url,…`。 | 空 | 否 |
| `KWORK_ANALYTICS` | 数据分析功能开关。设为 `1` 时启用（需商业许可配合）。 | 未设为关 | 否 |
| `KWORK_COLLAB` | 实时协同功能开关。设为 `1` 时启用（需商业许可配合）。 | 未设为关 | 否 |
| `KWORK_WATERMARK_OPS` | 运营与技术支持会话强制启用水印。非 `false` 即开启。 | 开启 | 否 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry 链路追踪数据导出端点。 | 空 | 否（启用 obs 时为 `http://otel-collector:4318`） |
| `KWORK_LOKI_URL` | 推送日志数据的 Loki 服务地址。 | 空 | 否（启用 obs 时为 `http://loki:3100/loki/api/v1/push`） |

### 数据库配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_DATABASE_URL` | 运行时数据库连接（`kwork_app`）。 | 空 | 生产环境必填 |
| `KWORK_AUDIT_DATABASE_URL` | 审计数据库连接。 | 同 `KWORK_DATABASE_URL` | 否 |
| `KWORK_MIGRATE_DATABASE_URL` | 仅供 migrate 迁移命令使用的连接串（需具备 schema 所有者权限）。 | 空 | 执行 migrate 命令时必填 |
| `KWORK_MIGRATE_AUDIT_DATABASE_URL` | 仅供 migrate 迁移审计库使用的连接串。 | 未设置则使用 `KWORK_MIGRATE_DATABASE_URL` | 否 |
| `KWORK_DB_MAX_CONNS` | 每个连接池在每个实例副本中的最大连接数。 | `25` | 否 |
| `KWORK_DB_MAX_IDLE_CONNS` | 每个连接池在每个实例副本中的最大空闲连接数。不得超过 `KWORK_DB_MAX_CONNS`。 | `10` | 否 |

> **数据库连接池特性**
>
> - 连接空闲 5 分钟后自动回收，单个连接最长存活 1 小时（未开放配置）。
> - 若使用 PgBouncer 代理数据库连接，**只能使用 session 模式**。
> - 若数据库连接串中未包含 `connect_timeout` 参数，系统会自动补齐 10 秒超时。

### 身份与认证配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_OIDC_JWKS_URL` | 校验 OIDC 令牌签名的公钥（JWKS）地址。 | 空 | 生产环境必填 |
| `KWORK_OIDC_JWKS_HOST` | 获取内部 JWKS 地址时的 Host 请求头。 | 空 | 使用内部网络地址时需要 |
| `KWORK_OIDC_ISSUER` | 令牌签发者标识（`iss`）。生产环境强制校验。 | 空（生效为 `https://id.{base}`） | 生产环境必填 |
| `KWORK_ZITADEL_URL` | Zitadel 管理 API 服务地址。 | 空 | 执行 bootstrap 或开通租户时需要 |
| `KWORK_ZITADEL_HOST` | Zitadel 管理 API 的 Host 请求头。 | 空 | 执行 bootstrap 或开通租户时需要 |
| `KWORK_ZITADEL_PAT` | Zitadel provisioner 个人访问令牌（PAT）。 | 空 | 开通租户时需要 |
| `KWORK_ZITADEL_PAT_FILE` | 包含 Zitadel PAT 令牌的文件路径。 | 空 | 开通租户时需要 |
| `KWORK_ZITADEL_BOOTSTRAP` | bootstrap 引导输出的 JSON 配置字符串。 | 空 | 重新执行引导时沿用已有凭据 |
| `KWORK_ZITADEL_BOOTSTRAP_FILE` | 包含 bootstrap 引导输出 JSON 的文件路径。 | 空 | 重新执行引导时沿用已有凭据 |
| `KWORK_BOOTSTRAP_OUT` | bootstrap 凭据输出保存目录（供 Helm hook 使用）。 | 空 | 否 |
| `KWORK_OPS_ADMINS` | bootstrap 阶段授予 `platform.ops` 角色的管理员登录名列表。 | 空 | 否 |
| `KWORK_LOGIN_PAGE` | 自建登录页功能开关，取值为 `on` 或 `off`。 | 空 | 仅在 bootstrap 时使用 |
| `KWORK_IDP_ALLOW_PRIVATE` | 是否允许租户配置的企业 IdP 使用 http 协议或内网私有地址。 | `false` | 否 |
| `KWORK_CONNECTOR_BACKEND_URL` | 企业 IdP 回调协作连接的后端服务通信地址。 | 空（生效为公开身份地址） | 否 |
| `KWORK_WECOM_API_BASE` | 企业微信 API 模拟器地址。 | 空（生效为公网微信地址） | 仅开发环境使用 |
| `KWORK_WECOM_LOGIN_BASE` | 企业微信登录模拟器地址。 | 空（生效为公网微信地址） | 仅开发环境使用 |

> **模拟器限制**
>
> 在非 `dev` 环境下，若未开启 `KWORK_IDP_ALLOW_PRIVATE`，设置 `KWORK_WECOM_API_BASE` 或 `KWORK_WECOM_LOGIN_BASE` 会导致系统拒绝启动。

### 存储与密钥配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_BLOB` | 对象存储驱动类型，可选值为 `fs`（本地文件系统）或 `s3`（S3 兼容对象存储）。 | `fs` | 必填（必须是二者之一） |
| `KWORK_BLOB_SECRET` | fs 驱动预签名 HMAC 密钥（base64 编码的 32 字节）。 | 空 | 生产环境且使用 `fs` 时必填 |
| `KWORK_DATA_DIR` | fs 驱动在本地的文件存储目录。 | `./.data` | 否 |
| `KWORK_S3_ENDPOINT` | S3 兼容对象存储的服务端点地址。 | 空 | 生产环境且使用 `s3` 时必填 |
| `KWORK_S3_BUCKET` | S3 存储桶名称。 | 空 | 生产环境且使用 `s3` 时必填 |
| `KWORK_S3_PUBLIC_ENDPOINT` | 预签名给浏览器直接访问的 S3 公网端点地址。 | 空（文档说明为 `https://files.{base}`） | 否 |
| `KWORK_S3_REGION` | S3 存储区域标识。 | `us-east-1` | 否 |
| `KWORK_S3_PREFIX` | S3 存储桶内的对象键路径前缀。 | 空 | 否 |
| `KWORK_S3_ACCESS_KEY` | S3 存储桶访问凭据 Access Key。 | 空 | 使用 `s3` 驱动时需要 |
| `KWORK_S3_SECRET_KEY` | S3 存储桶访问凭据 Secret Key。 | 空 | 使用 `s3` 驱动时需要 |
| `KWORK_S3_PATH_STYLE` | 是否使用路径风格（Path-Style）访问。SeaweedFS 与 MinIO 设为 `true`；AWS、阿里云 OSS、腾讯云 COS 设为 `false`。 | `true` | 否 |
| `KWORK_STORAGE_ALLOW_PRIVATE` | 是否允许租户自带存储使用 http 协议或内网私有地址。私有化部署通常设为 `true`。 | `false` | 否 |
| `KWORK_SECRETS` | 密钥管理驱动类型，可选值为 `local`（本地主密钥）或 `openbao`（OpenBao 服务）。 | `local` | 必填（必须是二者之一） |
| `KWORK_MASTER_KEY` | local 驱动下的系统主密钥（base64 编码的 32 字节）。 | 空 | 生产环境且使用 `local` 时必填 |
| `KWORK_OPENBAO_ADDR` | OpenBao 密钥管理服务地址。 | 空 | 生产环境且使用 `openbao` 时必填 |
| `KWORK_OPENBAO_ROLE_ID` | OpenBao AppRole 认证的 Role ID。需与 Secret ID 成对配置。 | 空 | 生产环境且使用 `openbao` 时必填（与 Token 二选一） |
| `KWORK_OPENBAO_SECRET_ID` | OpenBao AppRole 认证的 Secret ID。需与 Role ID 成对配置。 | 空 | 生产环境且使用 `openbao` 时必填（与 Token 二选一） |
| `KWORK_OPENBAO_TOKEN` | OpenBao bootstrap 访问令牌。 | 空 | 生产环境且使用 `openbao` 时必填（与 Role ID/Secret ID 二选一） |
| `KWORK_OPENBAO_TRANSIT` | OpenBao Transit 密钥引擎挂载路径。 | 空（适配器默认 `transit`） | 否 |
| `KWORK_OPENBAO_KV` | OpenBao KV 密钥引擎挂载路径。 | 空（适配器默认 `secret`） | 否 |
| `KWORK_OPENBAO_PREFIX` | OpenBao 内部路径前缀。 | 空（适配器默认 `kwork`） | 否 |
| `KWORK_ASSERTION_KEY` | Ed25519 种子私钥，用于签名断言、委托令牌与紧急访问（break-glass）。**所有服务模块必须保持相同**。 | 空 | 生产环境必填 |
| `KWORK_ASSERTION_KID` | 断言签名的密钥标识 ID。 | `k3-1` | 否 |

### 模型、搜索与 Agent 配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_LLM_BASE_URL` | OpenAI 兼容的大模型 API 服务端点。 | 空 | 需要使用模型时配置 |
| `KWORK_LLM_API_KEY` | 大模型网关或上游服务 API Key。 | 空 | 视上游认证要求配置 |
| `KWORK_LLM_ADMIN_URL` | Bifrost 模型网关管理 API 地址。未设置时表示不同步供应商。启用 `--shell` 或 `--llm` 时写入。 | 空 | 否 |
| `KWORK_LLM_ALLOW_PRIVATE` | 是否允许租户自带模型（BYO）连接内网私有地址或使用 http 协议。 | `false` | 否 |
| `KWORK_SERVICE_MODEL` | 后台异步任务默认使用的大模型 ID。未设置时使用租户默认配置。 | 空 | 否 |
| `KWORK_EMBED_MODEL` | 语义检索嵌入模型 ID。未设置时仅支持关键词检索。 | 空 | 否 |
| `KWORK_WEBSEARCH_ALLOW_PRIVATE` | 是否允许运营控制台「模型」→「联网搜索」中填写的接口地址位于私网，仅测试使用。联网搜索服务（DeepSeek 搜索）在运营控制台配置，不使用环境变量。 | `false` | 否 |
| `KWORK_WEBSEARCH_PER_MINUTE` | 单个组织每分钟允许发起的联网搜索请求次数上限。 | `20` | 否 |
| `KWORK_TEMPORAL_ADDR` | Agent 运行时 Temporal 服务的访问地址。 | 空 | 启用了 `agent-runtime` 模块时必填 |
| `KWORK_AGENT_DRAIN_S` | 服务停止时 Agent 任务的排空等待时间（秒）。设为 `0` 表示立即取消任务。 | `60` | 否 |
| `KWORK_AGENT_API_URL` | Agent 运行时调用平台 API 的地址。未设置表示在当前进程内部调用。 | 空 | 拆分部署时需要 |
| `KWORK_AGENT_ENABLED` | 工作台界面是否展示助手入口与定时任务。启用 `--shell` 时写入 `true`。 | `false` | 否 |
| `KWORK_OBJECTS_OPS_URL` | Draft 草稿调用对象引擎的服务通信地址。未设置表示在当前进程内部调用。 | 空 | 否 |
| `KWORK_LANGFUSE_URL` | 单租户大模型调用追踪项目地址。启用 `obs-llm` 组件时配置。 | 空 | 否 |
| `KWORK_PDF_URL` | Gotenberg PDF 转换服务地址。使用 `onprem` 环境包时写入。 | 空 | 否 |

> **Temporal 与停机排空细节**
>
> - 若未配置 Temporal（`KWORK_TEMPORAL_ADDR` 为空），助手与 Agent 相关接口返回 503 错误，服务进程不会退出。
> - 容器的停止宽限时间（`stop_grace_period`，Compose 中设为 90 秒）必须大于排空等待时间 `KWORK_AGENT_DRAIN_S`。

### 限流与运行时配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_APP_RPS` | 单个应用安装实例允许的持续请求速率（RPS）。配置为 `0` 时使用网关默认限额：持续 50 RPS，突发 100 RPS，并发 32。 | `0` | 否 |
| `KWORK_APP_ANON_CEILING` | 全应用匿名请求合计上限倍数。即持续 500 RPS。 | `10` | 否 |
| `KWORK_APP_WS_PER_INSTALL` | 单个应用安装实例在每个副本中的 WebSocket 连接数上限。 | `200` | 否 |
| `KWORK_APP_WS_PER_USER` | 单个成员在单个应用中每个副本的 WebSocket 连接数上限。 | `10` | 否 |
| `KWORK_REDIS_URL` | 跨副本共享限流计数器的 Redis 连接串。未设置时每个副本独立在本地计数。设了之后启动若无法连接 Redis，服务进程将直接退出。 | 空 | 否（多副本部署建议配置） |
| `KWORK_RUNTIME` | 托管第三方独立软件开发商（ISV）应用的容器运行时类型，可选 `docker`。未设置表示不启用托管运行。启用 `--apps` 时写入。 | 空 | 否 |
| `KWORK_RUNTIME_HOST` | 容器引擎通信地址。Compose 常见值为 `http://app-runner:2375`。 | 空 | 启用托管运行时时需要 |
| `KWORK_RUNTIME_NETWORK` | 应用沙箱容器所属的网络名称。Compose 中配置为 `kwork_apps`。 | 空 | 否 |
| `KWORK_RUNTIME_OCI` | 安全容器 OCI 运行时名称（例如 `runsc`）。 | 空 | 否 |
| `KWORK_WEBHOOK_ALLOW_PRIVATE` | 是否允许 Webhook 回调推送使用 http 协议或内网私有地址。 | `false` | 否 |
| `KWORK_PURGE_GRACE_DAYS` | 租户注销后到其数据可彻底清除的宽限保留天数。 | `7` | 否 |

### 审计归档与计费配置

| 变量名 | 作用说明 | 默认值 | 必填要求 |
|---|---|---|---|
| `KWORK_AUDIT_ARCHIVE` | 审计日志封存分段开关。非 `false` 即开启。 | 开启 | 否 |
| `KWORK_AUDIT_ARCHIVE_BUCKET` | 具备对象锁保护的审计日志归档专用存储桶。未配置时使用平台默认存储桶且无对象锁。 | 空 | 否 |
| `KWORK_AUDIT_RETENTION_DAYS` | 审计日志对象锁定保留天数。 | `0` | 否 |
| `KWORK_AUDIT_LOCK_MODE` | 对象锁定合规模式，可选 `COMPLIANCE` 或 `GOVERNANCE`。 | `COMPLIANCE` | 否 |
| `KWORK_AUDIT_SEAL_AFTER_HOURS` | 封存多少小时之前产生的审计事件。 | `24` | 否 |
| `KWORK_AUDIT_ONLINE_DAYS` | 归档后从在线数据库中删除清理的天数。设为 `0` 表示不从在线库中删除。 | `0` | 否 |
| `KWORK_BILLING_PROVIDER` | 平台订阅计费提供商。未设置时表示只生成账单开票而不实际扣款；可设为 `sandbox` 进行沙箱测试。 | 空 | 否 |
| `KWORK_BILLING_CURRENCY` | 无定价订阅时的计量计费币种。Compose 与参考配置中通常为 `CNY`。 | 空 | 否 |

### 开发模拟器变量

以下变量属于开发调试模拟器，仅供本地开发环境使用：

- `KWORK_PAY_WECHAT_BASE`：微信支付模拟器接口地址。
- `KWORK_PAY_ALIPAY_BASE`：支付宝支付模拟器接口地址。
- `KWORK_WECHAT_MP_API_BASE`：微信公众平台 API 模拟器地址。
- `KWORK_WECHAT_MP_AUTHORIZE_BASE`：微信公众平台网页授权模拟器地址。
- `KWORK_SMS_ALIYUN_BASE`：阿里云短信模拟器接口地址。
- `KWORK_SMS_TENCENT_BASE`：腾讯云短信模拟器接口地址。

> **生产环境禁止使用模拟器**
>
> 在生产环境（`KWORK_ENV≠dev`）中，一旦配置了上述任何一个模拟器变量，系统将直接拒绝启动并退出。

除上述模拟器变量外，系统还提供以下辅助网络与通知变量：

- `KWORK_WECHAT_MP_EGRESS_IPS`：对外网络出口 IP 地址列表（以逗号分隔），用于租户管理员填入微信公众平台的 IP 白名单。若未配置，界面会提示联系管理员。
- `KWORK_OUTREACH_LINK_BASE`：营销退订链接的基础地址。未配置时默认使用 `KWORK_PUBLIC_URL`。
- `KWORK_PAYSIM_ADDR`：支付模拟器服务（`paysim` 命令）的监听地址，默认 `:9100`。

### 部署环境与凭据变量（.env）

执行安装脚本 `install.sh` 时会自动在 `deploy/compose/.env` 中生成以下底层基础设施变量：

| 变量名 | 作用说明 |
|---|---|
| `BASE_DOMAIN` / `ACME_EMAIL` / `OPS_BIND` / `OPS_TLS` | 网关基础域名、ACME 证书申请通知邮箱、运营后台绑定地址与 TLS 模式。 |
| `PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD` | 首个平台管理员登录邮箱与初始生成的密码。 |
| `OPS_ADMINS` / `OPS_SUPPORT` | 额外授权的完整运营人员与只读运营人员邮箱列表（重新执行安装脚本时授权）。 |
| `POSTGRES_PASSWORD`、`KWORK_APP_DB_PASSWORD`、`ZITADEL_DB_PASSWORD`、`ZITADEL_MASTERKEY` | 数据库超级用户密码、主应用数据库密码、Zitadel 数据库密码及主加密密钥。 |
| `BI_DB_PASSWORD`、`BI_OPS_DB_PASSWORD`、`SUPERSET_DB_PASSWORD`、`LANGFUSE_DB_PASSWORD` | 数据分析、运营看板、Superset 与 Langfuse 数据库角色的访问密码。 |
| `S3_ACCESS_KEY` / `S3_SECRET_KEY` | 存储凭据，映射到主程序的 `KWORK_S3_ACCESS_KEY` 与 `KWORK_S3_SECRET_KEY`。 |
| `OPENBAO_ROLE_ID` / `OPENBAO_SECRET_ID` | OpenBao AppRole 凭据，映射到主程序的 `KWORK_OPENBAO_ROLE_ID` 与 `KWORK_OPENBAO_SECRET_ID`。 |
| `OPS_COOKIE_SECRET`、`OPS_PROXY_TOKEN`、`OPS_OIDC_CLIENT_*` | 运营后台单点登录（SSO）与网关认证代理所需的密钥凭据。 |
| `CUBE_API_SECRET`、`SUPERSET_*`、`LANGFUSE_*`、`CLICKHOUSE_PASSWORD` | 各辅助分析与追踪工具的通信密钥与访问密码。 |
| `KWORK_BRAND_DIR` | 品牌静态资源目录路径，默认 `../../brand/default`。 |
| `ALERTMANAGER_CONFIG` / `ALERTMANAGER_SECRETS` | 告警通知接收方配置文件路径与密钥。 |
| `BACKUP_*` | 数据库自动化备份相关配置，详细说明参见[备份与恢复](/deploy/backup)。 |

> **内置 CA 代理配置**
>
> 若需要为代理服务指定内置根证书，可在可选配置文件 `deploy/compose/oauth2-proxy.env` 中配置 `OAUTH2_PROXY_PROVIDER_CA_FILES=…`。

### Helm 配置映射

在 Kubernetes 环境下通过 Helm 部署（`deploy/helm/kwork`）时：

- **值文件映射**：`values.yaml` 中的 `secrets.*`、`database.maxConns`、`storage.*`、`llm.*`、`agent.*` 映射为对应的 `KWORK_*` 环境变量。
- **Secret 拆分管理**：系统拆分为三个独立的 Kubernetes Secret：
  - 运行时应用 Secret
  - 数据库迁移（migrate）所有者 Secret
  - 运营后台 cookie 认证 Secret
- **避免端口变量污染**：Chart 配置中已固定设置 `enableServiceLinks: false`，防止 Kubernetes 自动为名为 `kwork` 的 Service 注入 `KWORK_PORT` 环境变量，从而避免污染应用程序的端口配置。

## 状态说明

### 启动校验机制

系统在每次启动时按以下状态分支进行配置校验：

```
启动检查 → 判断 KWORK_ENV
         ├─ dev 模式 ──→ 跳过必填项校验，允许使用内存存储与临时密钥
         └─ prod 模式（或任何非 dev 值）
              ├─ 检查必填项完整 ──→ 校验通过，正常启动
              └─ 缺失任一必填项 ──→ 拒绝启动，终端打印缺失项并退出
```

若生产模式缺少必填项，控制台会列出缺失项并提示由 `install.sh` 生成密钥，然后退出。

### 变更生效与热重载

| 配置类型 | 生效机制 |
|---|---|
| 普通环境变量 | 修改后必须重启容器或 Pod 才能生效。 |
| 商业许可 `modules` 或 `features` | 修改授权模块或功能特性后必须重启服务生效。 |
| 商业许可席位与应用清单 | 支持热加载，修改后自动生效无需重启。 |
| Caddy 网关配置 | 修改 Caddyfile 后执行 `caddy reload` 热加载生效。 |
| Prometheus 与 OTel 配置文件 | 修改后需执行 `docker compose restart otel-collector prometheus` 重启容器生效。 |

## 让助手帮你做

环境变量与部署配置属于系统底层基础设施，不是助手（Agent）的操作面：

- 助手无法查看、修改或应用任何系统级环境变量。
- 组织管理员若需要配置日常业务策略，可以在工作台打开「我的组织」，通过图形界面或让助手协助配置组织内部的模型与存储。

## 设置

系统没有图形化的设置界面。所有系统级运行参数、监听端口、存储后端、限流配额与密钥均通过本页列出的环境变量及配置文件进行配置。

## 注意事项

- **与其他应用的关系**：几乎所有应用的行为上限、存储、模型与登录均读取这些环境变量。例如修改 `KWORK_APP_RPS` 会影响所有应用（`{app}.apps.{base}`）的请求速率上限；修改 `KWORK_EMBED_MODEL` 会影响全平台的语义检索能力；修改 `KWORK_AGENT_ENABLED` 会影响工作台界面是否展示助手入口与定时任务。
- **断言密钥保持一致**：修改 `KWORK_ASSERTION_KEY` 时，必须同时更新 `kwork` 主服务与 `kwork-agent` 容器，否则断言委托令牌会失效。
- **Redis 连通性强依赖**：若显式配置了 `KWORK_REDIS_URL`，启动时若无法连接 Redis，服务将直接报错退出。
- **生产环境禁用开发模拟器**：在生产环境（`KWORK_ENV≠dev`）中，严禁配置任何以 `_BASE` 结尾的开发模拟器变量，否则系统拒绝启动。
- **许可证变更生效差异**：修改许可证中的 `modules` 或 `features` 需重启服务；席位配额与应用清单支持热加载。
- **数据库连接数上限规划**：部署时需确保所有实例副本的连接池配额之和小于数据库最大连接数：
  副本数 ×（连接池数 × KWORK_DB_MAX_CONNS + 1）< 数据库最大连接数（max_connections）
  并且需要为 Zitadel、Temporal 与数据库迁移预留充足的连接。
- **Agent 停机排空宽限期**：容器的停止宽限时间（`stop_grace_period`，Compose 中默认 90 秒）必须大于排空等待时间 `KWORK_AGENT_DRAIN_S`（默认 60 秒）。
- **配置文件安全权限**：`deploy/compose/.env` 文件权限必须保持为 600，包含数据库密码与主密钥，禁止将真实凭据文件提交至版本控制系统。

## 目前不支持

- **平台订阅在线支付渠道**：平台订阅目前尚未实现微信支付与支付宝支付渠道（租户自身的收款业务通过[支付渠道](/admin/payments)独立配置）。
- **图形化实例配置页面**：系统尚未提供用于修改环境变量的图形化「实例配置」管理界面。

## 常见问题

### 为什么在生产环境中启动系统时直接报错退出，提示缺少必填配置？
生产环境（`KWORK_ENV` 不是 `dev`）会进行严格的配置项校验。若缺少基础域名 `KWORK_BASE_DOMAIN`、数据库连接 `KWORK_DATABASE_URL`、身份公钥 `KWORK_OIDC_JWKS_URL`、断言密钥 `KWORK_ASSERTION_KEY`，或存储与密钥驱动的必填项未填写，系统会拒绝启动并在终端列出所有缺失项。你可以使用安装脚本 `install.sh` 重新生成配置或手动补齐缺失项。

### 修改了 `.env` 文件后，为什么运行中的服务没有生效？
Raise 仅在容器启动时读取环境变量，不会在修改文件后自动热重载。在 Docker Compose 环境下，需要执行 `docker compose --env-file ../versions.env --env-file ../packs/{pack}.env --env-file .env up -d` 重新拉起容器；在 Helm 部署中，需要更新 Secret 或配置校验和以触发 Pod 滚动重启。此外，若修改了 `otelcol.yaml` 或 `prometheus.yml`，需执行 `docker compose restart otel-collector prometheus`；修改 Caddyfile 需执行 `caddy reload`。

### 为什么配置了 `KWORK_REDIS_URL` 之后，服务无法正常启动？
未配置 `KWORK_REDIS_URL` 时，各副本在本地内存中独立计算应用限流；一旦显式配置了 `KWORK_REDIS_URL`，系统会在启动时强校验 Redis 连通性。如果网络不通或 Redis 未就绪，服务将直接报错退出。多副本部署建议使用 Redis，但必须确保 Redis 服务正常可达。

### 可以在测试或预发环境中使用 `KWORK_ENV=dev` 吗？
不得在任何对外环境中使用 `KWORK_ENV=dev`。`KWORK_ENV=dev` 模式会跳过生产必填项校验，并允许使用内存存储与临时密钥，仅供本地开发调试。任何对外环境或正式生产环境必须将 `KWORK_ENV` 设为 `prod`。

### 为什么在生产环境中配置了 `KWORK_PAY_WECHAT_BASE` 或 `KWORK_SMS_ALIYUN_BASE` 会导致服务无法启动？
这一类以 `_BASE` 结尾的变量属于开发模拟器。在非 `dev` 环境下，系统禁止使用模拟器变量，一旦检测到配置会直接拒绝启动以防止测试数据污染或安全漏洞。