pikasTech-unidesk/docs/reference/config.md

# UniDesk Configuration Reference

根目录 `config.json` 是 UniDesk CLI 的唯一配置来源。CLI 启动时必须完整校验配置结构，读取失败或字段不合法时直接返回 JSON 错误，不允许静默 fallback。

## Runtime

TypeScript 运行时固定为 Bun for CLI, frontend, provider-gateway and TypeScript user services. backend-core is a Rust service; Rust build/check must follow the D601 boundary in `docs/reference/dev-environment.md`. 本机根 CLI 使用 `bun scripts/cli.ts <command>`；SSH/WSL/k3s 透传使用 `trans <route> ...`。

## Network Ports

`config.json` 中保留 core、frontend、devFrontend、database、providerIngress 和 providerData 的端口字段。frontend、devFrontend 与 providerIngress 是面向浏览器/Provider 的公开入口；providerData 是 `host.ssh.tcp-pool` 使用的数据面 TCP 端口，由 provider-gateway 主动连入 main server，默认主机端口为 `18084`、backend-core 容器端口为 `8082`。devFrontend 是 D601 `unidesk-dev` 的薄代理入口，权威规则见 `docs/reference/dev-environment.md`。core 不允许映射公网。database 的 `port` 字段用于 D601 Code Queue 的受限 PostgreSQL 端口映射和公网阻断测试，必须配合 `network.restrictedHostAccess` 的来源白名单限制到 D601 出口地址，不能作为任意公网数据库入口。

## Auth

`auth.username` 和 `auth.password` 是 frontend 登录凭据，默认值分别为 `admin` 和 `Liang6516.`。`auth.sessionSecret` 用于签名 frontend HttpOnly Cookie，`auth.sessionTtlSeconds` 控制登录会话有效期；修改后必须重新启动 Docker 栈以刷新派生环境变量。

## Provider Gateway Metrics And Upgrade

`providerGateway.metrics.diskPath` 指定主 server 本机 provider 的硬盘采样路径，默认是 `/`。`providerGateway.upgrade` 定义主 server provider 远程升级所需的 Compose project、service、仓库挂载路径、派生 env 文件和 updater runner 镜像；这些字段由 CLI 写入 `.state/docker-compose.env`，主 server Compose 仍保持显式配置。外部计算节点可以使用 `provider attach` 的简化 env：只写 `UNIDESK_MASTER_SERVER` 与 `PROVIDER_ID`，provider-gateway 会派生公网 provider ingress URL、默认 labels、心跳、Docker socket、监控路径和升级 Compose 名称，并通过 Docker inspect 反查 `/workspace` 的宿主挂载源；显式 `PROVIDER_*` 环境变量仍优先级最高。远程升级没有 `enabled` 开关，长期接入节点必须具备 `mode: "schedule"` 一键升级能力；如果节点不满足升级前置条件，应修正 Docker socket、仓库挂载或显式覆盖 `PROVIDER_UPGRADE_*`，而不是在配置中禁用升级。

## SSH Forwarding

`sshForwarding` 定义 provider-gateway 维护专用 Host SSH / WSL SSH 桥的显式配置。CLI 会把 `sshForwarding.keyDir` 写入 `.state/docker-compose.env` 的 `UNIDESK_HOST_SSH_KEY_DIR`，Compose 将该目录只读挂载到 provider-gateway 的 `/run/host-ssh`，并把 `sshForwarding.host`、`sshForwarding.port`、`sshForwarding.user` 映射为 `HOST_SSH_HOST`、`HOST_SSH_PORT`、`HOST_SSH_USER`。目录中必须存在 `id_ed25519` 私钥且权限收紧，provider-gateway 才会把 `hostSshKeyPresent` 上报为 true，并允许 `host.ssh` 维护探测；该桥只用于故障诊断和 WSL 维护，不替代 Docker socket 调度。

## User Services

`microservices` 定义挂载在计算节点或主 server Docker 中的非核心用户服务。用户服务是挂在 UniDesk 核心服务上的用户业务能力，缺少这些服务时 UniDesk 核心仍必须能运行。该数组只保存业务仓库 URL、commit id、业务仓库自身 Dockerfile/docker-compose 引用、provider 映射、节点后端端口和 UniDesk frontend 集成入口；不得把业务全量代码复制进 UniDesk。`backend.public` 必须为 `false`，`backend.frontendOnly` 必须为 `true`，`backend.allowedPathPrefixes` 必须限制到业务 API 前缀，`backend.allowedMethods` 必须显式列出允许代理的 HTTP 方法；浏览器只能通过 frontend 同源代理访问这些后端。详细规则见 `docs/reference/microservices.md`。

主 server 承载的 Todo Note 用户服务使用 `providerId=main-server`、`nodeBaseUrl=http://todo-note:4211` 和 `allowedMethods=["GET","HEAD","POST","DELETE"]`，数据库使用主 PostgreSQL；Code Queue 使用 `deployment.mode=k3sctl-managed`、`backend.proxyMode=k3sctl-adapter-http` 和 `nodeBaseUrl=k3s://code-queue`，只允许通过 frontend/backend-core -> `k3sctl-adapter` -> Kubernetes API service proxy -> k3s/k8s Service 单一路径访问，不能配置业务容器直连、NodePort 或 provider-gateway direct path；D601 的 FindJob 只允许 `GET/HEAD` 展示型读取路径；D601 的 Pipeline 允许 `GET/HEAD/POST`，其中 `POST` 只用于 Pipeline 后端 `/api/node-control/...` 的 append prompt、guide 和 redo/restart 等受控 node 操作。

## Compose Env Generation

Docker Compose 本身不读取 JSON，因此 CLI 会从 `config.json` 生成 `.state/docker-compose.env`。该文件是派生状态，不应手写；如需改常规端口、token、provider 标签、登录凭据或主机名，应修改 `config.json` 后重新运行 CLI。`network.restrictedHostAccess.bindHost` 派生出 `UNIDESK_DATABASE_BIND_HOST` 和 `UNIDESK_OA_EVENT_FLOW_BIND_HOST`，`allowedSourceCidrs` 由 `server start/rebuild` 写入 `DOCKER-USER` 来源白名单；将 bind host 设为 `0.0.0.0` 时 `allowedSourceCidrs` 不能为空。CLI 会在保留当前日志前缀的同时刷新新增配置键，避免旧 env 文件遗漏字段。

## Secrets

当前配置面向主 server 开发部署，包含开发用数据库密码、provider token 和默认登录密码。公网长期运行前必须在 `config.json` 中修改这些值，并重新启动栈以刷新派生环境文件。