用户手册

外观

配置参考 ​

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_* 环境变量。

界面一览 ​

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

  • 运营台「服务导航」：进入运营台的「服务导航」，可以查看各已部署组件的运行状态与健康信息。
  • 容器配置文件重启：修改了由容器启动时读取的文件（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_DIRk3 构建工件下载目录。/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_ENDPOINTOpenTelemetry 链路追踪数据导出端点。空否（启用 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_URLZitadel 管理 API 服务地址。空执行 bootstrap 或开通租户时需要
KWORK_ZITADEL_HOSTZitadel 管理 API 的 Host 请求头。空执行 bootstrap 或开通租户时需要
KWORK_ZITADEL_PATZitadel provisioner 个人访问令牌（PAT）。空开通租户时需要
KWORK_ZITADEL_PAT_FILE包含 Zitadel PAT 令牌的文件路径。空开通租户时需要
KWORK_ZITADEL_BOOTSTRAPbootstrap 引导输出的 JSON 配置字符串。空重新执行引导时沿用已有凭据
KWORK_ZITADEL_BOOTSTRAP_FILE包含 bootstrap 引导输出 JSON 的文件路径。空重新执行引导时沿用已有凭据
KWORK_BOOTSTRAP_OUTbootstrap 凭据输出保存目录（供 Helm hook 使用）。空否
KWORK_OPS_ADMINSbootstrap 阶段授予 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_SECRETfs 驱动预签名 HMAC 密钥（base64 编码的 32 字节）。空生产环境且使用 fs 时必填
KWORK_DATA_DIRfs 驱动在本地的文件存储目录。./.data否
KWORK_S3_ENDPOINTS3 兼容对象存储的服务端点地址。空生产环境且使用 s3 时必填
KWORK_S3_BUCKETS3 存储桶名称。空生产环境且使用 s3 时必填
KWORK_S3_PUBLIC_ENDPOINT预签名给浏览器直接访问的 S3 公网端点地址。空（文档说明为 https://files.{base}）否
KWORK_S3_REGIONS3 存储区域标识。us-east-1否
KWORK_S3_PREFIXS3 存储桶内的对象键路径前缀。空否
KWORK_S3_ACCESS_KEYS3 存储桶访问凭据 Access Key。空使用 s3 驱动时需要
KWORK_S3_SECRET_KEYS3 存储桶访问凭据 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_KEYlocal 驱动下的系统主密钥（base64 编码的 32 字节）。空生产环境且使用 local 时必填
KWORK_OPENBAO_ADDROpenBao 密钥管理服务地址。空生产环境且使用 openbao 时必填
KWORK_OPENBAO_ROLE_IDOpenBao AppRole 认证的 Role ID。需与 Secret ID 成对配置。空生产环境且使用 openbao 时必填（与 Token 二选一）
KWORK_OPENBAO_SECRET_IDOpenBao AppRole 认证的 Secret ID。需与 Role ID 成对配置。空生产环境且使用 openbao 时必填（与 Token 二选一）
KWORK_OPENBAO_TOKENOpenBao bootstrap 访问令牌。空生产环境且使用 openbao 时必填（与 Role ID/Secret ID 二选一）
KWORK_OPENBAO_TRANSITOpenBao Transit 密钥引擎挂载路径。空（适配器默认 transit）否
KWORK_OPENBAO_KVOpenBao KV 密钥引擎挂载路径。空（适配器默认 secret）否
KWORK_OPENBAO_PREFIXOpenBao 内部路径前缀。空（适配器默认 kwork）否
KWORK_ASSERTION_KEYEd25519 种子私钥，用于签名断言、委托令牌与紧急访问（break-glass）。所有服务模块必须保持相同。空生产环境必填
KWORK_ASSERTION_KID断言签名的密钥标识 ID。k3-1否

模型、搜索与 Agent 配置 ​

变量名作用说明默认值必填要求
KWORK_LLM_BASE_URLOpenAI 兼容的大模型 API 服务端点。空需要使用模型时配置
KWORK_LLM_API_KEY大模型网关或上游服务 API Key。空视上游认证要求配置
KWORK_LLM_ADMIN_URLBifrost 模型网关管理 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_ADDRAgent 运行时 Temporal 服务的访问地址。空启用了 agent-runtime 模块时必填
KWORK_AGENT_DRAIN_S服务停止时 Agent 任务的排空等待时间（秒）。设为 0 表示立即取消任务。60否
KWORK_AGENT_API_URLAgent 运行时调用平台 API 的地址。未设置表示在当前进程内部调用。空拆分部署时需要
KWORK_AGENT_ENABLED工作台界面是否展示助手入口与定时任务。启用 --shell 时写入 true。false否
KWORK_OBJECTS_OPS_URLDraft 草稿调用对象引擎的服务通信地址。未设置表示在当前进程内部调用。空否
KWORK_LANGFUSE_URL单租户大模型调用追踪项目地址。启用 obs-llm 组件时配置。空否
KWORK_PDF_URLGotenberg 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_IDOpenBao 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_*数据库自动化备份相关配置，详细说明参见备份与恢复。

内置 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，包含数据库密码与主密钥，禁止将真实凭据文件提交至版本控制系统。

目前不支持 ​

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

常见问题 ​

为什么在生产环境中启动系统时直接报错退出，提示缺少必填配置？ ​

生产环境（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 环境下，系统禁止使用模拟器变量，一旦检测到配置会直接拒绝启动以防止测试数据污染或安全漏洞。