Codex
32 lines
2.8 KiB
Markdown
32 lines
2.8 KiB
Markdown
# UniDesk Configuration Reference
|
||
|
||
根目录 `config.json` 是 UniDesk CLI 的唯一配置来源。CLI 启动时必须完整校验配置结构，读取失败或字段不合法时直接返回 JSON 错误，不允许静默 fallback。
|
||
|
||
## Runtime
|
||
|
||
TypeScript 运行时固定为 Bun。根目录 CLI、backend-core、frontend 和 provider-gateway 都直接运行 `.ts` 入口；Docker 镜像使用 `oven/bun` 基础镜像，本机命令使用 `bun scripts/cli.ts`。
|
||
|
||
## Network Ports
|
||
|
||
`config.json` 中保留 core、frontend、database 和 providerIngress 的端口字段，但只有 frontend 与 providerIngress 允许映射到宿主机公网端口。core 和 database 的 `port` 字段用于测试公网阻断和历史兼容，实际服务只使用 Docker 内网 `containerPort`。
|
||
|
||
## Auth
|
||
|
||
`auth.username` 和 `auth.password` 是 frontend 登录凭据，默认值分别为 `admin` 和 `Liang6516.`。`auth.sessionSecret` 用于签名 frontend HttpOnly Cookie，`auth.sessionTtlSeconds` 控制登录会话有效期；修改后必须重新启动 Docker 栈以刷新派生环境变量。
|
||
|
||
## Provider Gateway Metrics And Upgrade
|
||
|
||
`providerGateway.metrics.diskPath` 指定资源监控页的硬盘采样路径，默认是 `/`。`providerGateway.upgrade` 定义远程升级 provider-gateway 所需的 Compose project、service、仓库挂载路径、派生 env 文件和 updater runner 镜像；这些字段由 CLI 写入 `.state/docker-compose.env`，provider-gateway 只通过 WebSocket 接受 `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 调度。
|
||
|
||
## Compose Env Generation
|
||
|
||
Docker Compose 本身不读取 JSON，因此 CLI 会从 `config.json` 生成 `.state/docker-compose.env`。该文件是派生状态，不应手写；如需改端口、token、provider 标签、登录凭据或主机名，应修改 `config.json` 后重新运行 CLI。CLI 会在保留当前日志前缀的同时刷新新增配置键，避免旧 env 文件遗漏字段。
|
||
|
||
## Secrets
|
||
|
||
当前配置面向主 server 开发部署，包含开发用数据库密码、provider token 和默认登录密码。公网长期运行前必须在 `config.json` 中修改这些值，并重新启动栈以刷新派生环境文件。
|