• 简体中文

      • API 配置

      源码运行时，API 从根目录 .env 读取这些变量；Docker Compose 也只读取这一份 .env，但会按消费者白名单仅把 API 所需变量注入 API 容器。PUBLIC_BASE_URL、日志、OpenTelemetry 和数据卷传输上限等公共值只填写一次，再由 Compose 同步给实际消费者。API 只在启动时读取并校验配置；修改后需要重启，显式配置的 ENV_FILE 不存在或无法解析时会拒绝启动。

      基础配置

      配置项名称默认值说明
      APP_ENVproduction选择 API 运行模式；可填 production 或 development。
      API_ADDR:8080设置 API 监听地址；填写 IP:端口 或 :端口。
      PUBLIC_BASE_URL生产环境必填设置用户访问平台及生成 kubectl kubeconfig Server 的可信根地址；生产环境填写用户实际访问的绝对 HTTPS URL，仅本机 localhost 或回环地址允许 HTTP。
      DATABASE_URL本地 PostgreSQL连接 PostgreSQL；填写 PostgreSQL 连接 URI。
      REDIS_ADDRredis://localhost:6379/0连接 Redis；填写 redis:// 或 rediss:// URI。
      REDIS_PASSWORD空设置 Docker Compose 内置 Redis 的密码；填写密码字符串，未启用认证时留空。
      SECRET_ENCRYPTION_KEY1空加密平台保存的凭据；填写稳定的非空密钥。
      INITIAL_ADMIN_EMAIL2空在全新数据库创建首个管理员；填写有效的纯邮箱地址。
      INITIAL_ADMIN_PASSWORD2空设置首个管理员的初始密码；填写 8–72 字节的强密码并通过 Secret 提供。
      INITIAL_ADMIN_NAME2空设置首个管理员的显示名称；填写名称或留空以使用邮箱。
      INITIAL_ADMIN_LANGUAGE2zh-CN设置首个管理员的语言；可填 zh-CN 或 en-US。
      APP_CORS_ORIGINS空允许浏览器跨域访问；填写逗号分隔的 HTTP(S) Origin。
      TRUSTED_PROXY_CIDRS4空建立客户端 IP 的可信转发边界；仅填写允许向 API 提供转发地址的代理出口 CIDR，多个值以逗号分隔，直连时留空。
      LOG_FORMATauto选择终端日志渲染；可填 auto、console 或 json，生产容器应使用 json。
      LOG_COLORauto控制 console 日志颜色；可填 auto、always 或 never，NO_COLOR 会强制关闭。
      LOG_LEVELinfo设置日志级别；可填 debug、info、warn 或 error。
      AI_ASSISTANT_AVAILABLEfalse控制 AI 助手是否可用；可填 true 或 false。
      AI_AGENT_BASE_URL空设置 API 访问 Agent 的地址；填写 HTTP(S) URL。
      AI_AGENT_TIMEOUT10s限制 API 对 Agent 的非流式请求时长；填写 Go duration（如 10s 或 1m），SSE 不受此项限制。
      AI_INTERNAL_SECRET3空鉴权 API 与 Agent 的内部请求；填写至少 32 字节的密钥。
      1. 说明：生产环境必须设置 SECRET_ENCRYPTION_KEY；更换后已有加密凭据将无法读取。
      2. 说明：这些配置只在数据库从未存在用户时创建首个管理员；已有有效管理员时不会覆盖账号或密码，已有用户但没有有效管理员时 API 会拒绝启动并要求先恢复管理员。
      3. 说明：API 与 Agent 必须使用同一个 AI_INTERNAL_SECRET。
      4. 说明：启用 Helm Chart 的 Ingress 时必须设置对应的 app.trustedProxyCidrs；优先填写 API 实际看到的专用 Ingress/反向代理来源及可信转发链代理出口，只有网络隔离能阻止其他 Pod 直连 API 时才可填写整段 Pod CIDR。不要填写客户端网段；API 会拒绝 0.0.0.0/0 和 ::/0。直连请求按 socket 对端限流，只有实际对端属于可信代理 CIDR 时才采用转发客户端 IP。公共 CLI 的 device start、device-code polling、authorization-code、refresh 和 revoke 分别使用独立来源桶。

      kubectl 网关不会根据请求 Host 猜测 kubeconfig Server；修改 PUBLIC_BASE_URL 后需要重启 API，并重新签发受影响的 kubeconfig。反向代理还必须原样转发 /kube/、支持 Upgrade、关闭流缓冲并避免记录原始查询字符串，具体见 Kubernetes (Helm) 部署。

      高级配置

      运行与开发

      配置项名称默认值说明
      ENV_FILE.env指定 API 读取的环境文件；填写有效文件路径，显式指定后文件缺失或格式错误会导致启动失败。
      APP_ENABLE_HSTS生产为 true控制 API 是否发送 HSTS Header；可填 true 或 false。
      APP_VERSION构建版本设置 API 对外报告的版本；填写版本字符串。
      LOCAL_ADMIN_FREE_QUOTA_CREDITS1000设置开发模式下首个管理员创建时发放的免费额度；填写非负 Credits 数值。

      数据库

      配置项名称默认值说明
      API_DB_MAX_OPEN_CONNS20限制每个 API 副本的数据库最大打开连接数；填写正整数。
      API_DB_MAX_IDLE_CONNS5限制每个 API 副本的数据库最大空闲连接数；填写非负整数。
      API_DB_CONN_MAX_LIFETIME30m限制 API 数据库连接总寿命；填写 Go duration，如 30m。
      API_DB_CONN_MAX_IDLE_TIME5m限制 API 数据库连接空闲时间；填写 Go duration，如 5m。

      指标与可观测

      配置项名称默认值说明
      METRICS_ENABLEDfalse控制是否暴露 Prometheus 指标；可填 true 或 false。
      METRICS_ADDR:9090设置指标服务监听地址；填写 IP:端口 或 :端口。
      METRICS_PATH/metrics设置指标接口路径；填写以 / 开头的 HTTP 路径。
      OTEL_EXPORTER_OTLP_ENDPOINT空设置遥测数据接收端；填写 Collector 的 OTLP/HTTP URL。
      OTEL_RESOURCE_ATTRIBUTES空设置 OpenTelemetry 资源属性；填写逗号分隔的 key=value。
      OTEL_EXPORTER_OTLP_HEADERS空鉴权 Collector 请求；填写逗号分隔的 key=value Header。
      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT空设置浏览器 Trace Relay 的接收端；填写 HTTP(S) URL。
      OTEL_EXPORTER_OTLP_TRACES_HEADERS空鉴权浏览器 Trace Relay 请求；填写逗号分隔的 key=value Header。

      数据卷导入与导出

      配置项名称默认值说明
      VOLUME_TRANSFER_MAX_BYTES100Gi限制单次数据卷导入或导出大小；填写 1Gi–5Ti 容量值。

      数据卷内容在客户端、API 和运行集群 Transfer Pod 之间直接流式传输，不需要对象存储、回调地址或 API 本地完整暂存。

      Docker Compose 与 Web 构建

      配置项名称默认值说明
      DEVOPS_IMAGE_TAGnightly选择 Docker Compose 使用的 API 和 Web 镜像版本；填写镜像标签。
      VITE_DOCS_BASE_URL官方文档站设置 Web 中的文档入口；填写构建时可用的 HTTP(S) URL。