pikasTech-unidesk/docs/reference/microservices.md

# UniDesk Microservices Reference

UniDesk microservice 是挂载到主 server 控制面的非核心业务后端。业务容器运行在计算节点 Docker 中，主 server 只保存仓库引用、commit id、Dockerfile/docker-compose 引用、provider 映射和前端集成配置，不把业务仓库整体复制进 UniDesk。

## Boundary

- microservice 后端端口默认只绑定计算节点本机地址，例如 `127.0.0.1:<port>`，不得直接暴露公网。
- 浏览器只访问 UniDesk frontend；frontend 通过同源 `/api/microservices/*` 代理到 backend-core，backend-core 再通过目标 provider-gateway 的 `microservice.http` 能力访问计算节点本机后端。
- backend-core REST API、database 和计算节点 microservice 后端都不得新增公网端口；公网入口仍只有 frontend 和 provider ingress。
- `microservice.http` 只允许 provider-gateway 访问 `http://127.0.0.1`、`http://localhost` 或 `http://host.docker.internal` 这类节点本地地址，并由 backend-core 的 `allowedPathPrefixes` 限制可代理路径。

## Config Contract

`config.json` 的 `microservices` 是 microservice 的唯一登记来源。每个条目必须包含：

- `id`、`name`、`providerId` 和 `description`，用于 CLI、backend-core 和 frontend 统一识别。
- `repository.url` 与 `repository.commitId`，用于记录业务代码的外部权威来源；UniDesk 不 vendoring 业务全量代码。
- `repository.dockerfile`、`repository.composeFile`、`repository.composeService` 和 `repository.containerName`，用于说明部署应复用业务仓库自身维护的 Dockerfile/docker-compose。
- `backend.nodeBaseUrl`、`backend.nodeBindHost`、`backend.nodePort`、`backend.proxyMode`、`backend.public=false`、`backend.frontendOnly=true`、`backend.allowedPathPrefixes` 和 `backend.healthPath`，用于定义计算节点端口到 UniDesk frontend-only 代理的映射。
- `development.providerId`、`development.sshPassthrough=true` 和 `development.worktreePath`，用于说明开发调试入口必须在计算节点上通过 UniDesk SSH 透传完成。
- `frontend.route` 和 `frontend.integrated=true`，用于说明该业务前端已经整合到 UniDesk React 控制台，而不是继续公开业务自身前端。

## Compute-Node Development Convention

非 UniDesk 核心功能开发不得默认占用主 server 有限主机资源。涉及 findjob 这类业务功能时，应通过 `bun scripts/cli.ts ssh <PROVIDER_ID> ...` 或 remote CLI SSH 透传进入计算节点，在计算节点本地业务仓库中开发、构建和调试；开发完成后，只把业务服务以 microservice 形式登记到 UniDesk。

业务仓库由业务系统自己维护，包括源码、Dockerfile、docker-compose、配置模板和业务测试。UniDesk 只引用业务仓库 URL、commit id、Dockerfile/docker-compose 路径和运行容器名；不得把业务全量代码复制到 `src/components/microservices/` 形成双维护。`src/components/microservices/` 只能放通用示例或 UniDesk 自有示例，不作为业务仓库镜像。

## D601 Microservices

当前 `D601` 同时承载以下 UniDesk microservice：

- `findjob`：FindJob 纯后端服务，UniDesk frontend 渲染岗位指标、岗位预览和草稿报告。
- `pipeline`：Pipeline v2 观测服务，UniDesk frontend 渲染组件矩阵、控制图、运行状态和证据日志摘要。

### FindJob On D601

当前 FindJob 作为 `id=findjob` 的 microservice 登记在 `config.json`：

- Provider：`D601`。
- 开发工作树：`/home/ubuntu/findjob`，开发和调试必须通过 UniDesk SSH 透传进入 D601。
- 代码引用：`https://gitee.com/Lyon1998/findjob` 与配置中的 `repository.commitId`。
- 部署引用：业务仓库自身 `Dockerfile`、`docker-compose.yml`、`composeService=server`、`containerName=findjob-server`。
- 节点后端：D601 上 `127.0.0.1:3254`，provider-gateway 容器内通过 `http://host.docker.internal:3254` 访问。
- 代理路径：只允许 `/api/` 前缀；`/` 上的业务旧前端即使仍存在，也不作为 UniDesk microservice 入口使用。
- UniDesk 前端：`微服务 / FindJob` React 页面负责展示指标、岗位预览、草稿报告和原始 JSON 显式查看按钮。

FindJob 在 UniDesk 语境中按纯后端服务管理：默认页面不得 iframe 或跳转到 findjob 自身前端，也不得直接暴露 D601 的 `3254` 到公网。UniDesk frontend 只能通过 `/api/microservices/findjob/health` 和 `/api/microservices/findjob/proxy/api/...` 访问 FindJob 后端。

### Pipeline On D601

当前 Pipeline v2 作为 `id=pipeline` 的 microservice 登记在 `config.json`：

- Provider：`D601`。
- 开发工作树：`/home/ubuntu/pipeline`，开发和调试必须通过 UniDesk SSH 透传进入 D601。
- 代码引用：`https://github.com/pikasTech/pipeline` 与配置中的 `repository.commitId`。
- 部署引用：业务仓库自身 `Dockerfile`、`docker-compose.yml`、`composeService=pipeline-webui`、`containerName=pipeline-v2-webui`。
- 节点后端：D601 上 `127.0.0.1:18082`，provider-gateway 容器内通过 `http://host.docker.internal:18082` 访问。
- 代理路径：只允许 `/health` 和 `/api/` 前缀；Pipeline 自身 WebUI 静态页面即使仍由 `pipeline-webui` 提供，也不作为 UniDesk microservice 入口使用。
- UniDesk 前端：`微服务 / Pipeline` React 页面负责展示 health、组件数量、pipeline 控制图、最近运行、OA/procedure 摘要和显式原始 JSON 按钮。

Pipeline 在 UniDesk 语境中按观测后端服务管理：默认页面不得 iframe 或跳转到 Pipeline 自身 WebUI，也不得直接暴露 D601 的 `18082` 到公网。UniDesk frontend 只能通过 `/api/microservices/pipeline/health` 和 `/api/microservices/pipeline/proxy/api/snapshot?...` 访问 Pipeline 后端；超大 snapshot 必须使用 `__unideskArrayLimit=registry.components:<limit>,runs:<limit>` 做展示级裁剪。

## CLI

- `bun scripts/cli.ts microservice list`：列出全部 microservice、provider 映射、仓库引用、后端映射和运行态容器摘要。
- `bun scripts/cli.ts microservice status findjob`：查看单个 microservice 的配置与运行态。
- `bun scripts/cli.ts microservice health findjob`：通过 backend-core -> provider-gateway -> D601 本机后端链路探测 FindJob `/api/health`。
- `bun scripts/cli.ts microservice proxy findjob /api/summary`：通过同一私有代理读取业务 API，适合人工验证，不用于公开业务端口。
- `bun scripts/cli.ts microservice health pipeline`：通过 backend-core -> provider-gateway -> D601 本机后端链路探测 Pipeline `/health`。
- `bun scripts/cli.ts microservice proxy pipeline '/api/snapshot?__unideskArrayLimit=registry.components:8,runs:3'`：读取 Pipeline snapshot 的有界预览，适合人工验证，不用于公开业务端口；若 body 仍超过 CLI 阈值，默认只输出 `bodyPreview`，需要完整 body 时显式追加 `--raw`。
- `bun scripts/cli.ts --main-server-ip 74.48.78.17 microservice health findjob`：在计算节点或其他非主 server 主机上通过公网 frontend remote CLI 进行同一验证，不需要主 server SSH key。

`debug dispatch D601 microservice.http --payload-json ...` 仅用于开发调试 provider-gateway 代理能力；正式验收和用户入口应优先使用 `microservice` 命令与 frontend 页面。

## Frontend Rules

microservice 前端必须整合到 `src/components/frontend/src/app.tsx` 的 TypeScript + React 组件中。默认展示必须是业务控件：指标卡、状态徽标、表格、草稿卡片、运行卡片、日志摘要、链接和字段摘要；只有操作员点击 `查看原始JSON` 时才允许打开原始 JSON 弹窗。

对于超大业务 JSON，backend-core 可把 `__unideskArrayLimit=<path>:<limit>` 作为 frontend-only 代理参数传给 provider-gateway，由 provider-gateway 在返回前裁剪指定 JSON 数组并写入 `_unidesk.arrayLimits` 元数据。该参数只用于控制 UniDesk 展示预览，不能替代业务后端自身分页 API 的长期设计。CLI 的 `microservice proxy` 还会对超过默认阈值的 body 做二次有界预览，防止人工验证时输出爆炸；只有显式 `--raw` 才允许倾倒完整 body。

## Verification

FindJob 和 Pipeline microservice 交付必须同时通过后端、CLI 和公网 frontend 验证：

- 在主 server 运行 `bun scripts/cli.ts microservice list`，确认 `findjob` 的 `providerId=D601`、`public=false`、`frontendOnly=true`、仓库 URL、commit id、`127.0.0.1:3254` 映射和 `findjob-server` 容器摘要可见。
- 在主 server 运行 `bun scripts/cli.ts microservice list`，确认 `pipeline` 的 `providerId=D601`、`public=false`、`frontendOnly=true`、仓库 URL、commit id、`127.0.0.1:18082` 映射和 `pipeline-v2-webui` 容器摘要可见。
- 运行 `bun scripts/cli.ts microservice health findjob` 与 `bun scripts/cli.ts microservice proxy findjob /api/summary`，确认真实链路经过 backend-core、WebSocket、D601 provider-gateway 和 D601 本机 FindJob 后端。
- 运行 `bun scripts/cli.ts microservice health pipeline` 与 `bun scripts/cli.ts microservice proxy pipeline '/api/snapshot?__unideskArrayLimit=registry.components:8,runs:3'`，确认真实链路经过 backend-core、WebSocket、D601 provider-gateway 和 D601 本机 Pipeline 后端。
- 在 D601 上用 `bun scripts/cli.ts ssh D601 ...` 调试业务仓库和容器，确认 `curl http://127.0.0.1:3254/api/health` 可用；不要把调试服务部署到主 server。
- 在 D601 上用 `bun scripts/cli.ts ssh D601 ...` 调试业务仓库和容器，确认 `curl http://127.0.0.1:18082/health` 和 `curl http://127.0.0.1:18082/api/snapshot` 可用；不要把 Pipeline 调试服务部署到主 server。
- 运行 `bun scripts/cli.ts e2e run`，确认 microservice 相关检查 passed，并确认 Playwright 访问的是公网 `http://74.48.78.17:18081/`。
- 登录公网 frontend，进入 `微服务 / 服务目录`、`微服务 / FindJob` 和 `微服务 / Pipeline`，确认能看到 D601 provider、仓库引用、后端私有映射、FindJob 指标和岗位预览、Pipeline 组件矩阵和最近运行；FindJob 页面必须显示真实数字指标、`HEALTH OK` 和非空岗位预览，Pipeline 页面必须显示 `Pipeline v2 工作台`、`Health OK`、组件数和最近运行，不能只停留在 loading 骨架；页面默认不得出现裸 JSON。