phptits
0d6cd37579
- Monorepo: NestJS API (Fastify) + React web (antd/ProComponents) + shared packages - PostgreSQL/Prisma (unified resources, relations graph, audit, events, jobs) - Auth/RBAC/workspace isolation, credential vault (AES-256-GCM) - Servers/SSH, Docker discovery & lifecycle, Job Center - Websites & deployments (git provider credential clone, env, health verification) - Domains/DNS (Cloudflare adapter), certificates (TLS probe), monitoring - Automation (cron/event/webhook HMAC + notifications), AI Gateway, MCP (29 tools) - AI chat window (LLM function-calling + rules fallback, SSE streaming, approvals) - Notes: Vditor WYSIWYG markdown editor, non-blocking autosave - Tests: 35 unit/security tests; UI audit clean (desktop+mobile, deep links)
173 lines
9.8 KiB
Markdown
173 lines
9.8 KiB
Markdown
# DevOS — Developer Work OS
|
||
|
||
统一管理服务器、容器、网站、域名、部署、监控与自动化的开发者工作操作系统。
|
||
架构遵循 `Docs/devos-v1/`（统一资源模型：Resource + Action + Event + Agent，模块化单体）。
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
| --- | --- |
|
||
| 后端 | NestJS 11 + Fastify 适配器 + zod DTO + Prisma 6 |
|
||
| 前端 | React 18 + Ant Design 5 + ProComponents + TanStack Query + Zustand |
|
||
| 数据 | PostgreSQL 16 + Redis 7（Docker Compose） |
|
||
| 运行时 | Bun（包管理/测试/运行；后端编译为 CommonJS 后由 Bun/Node 运行） |
|
||
| 集成 | SSH (ssh2)、Docker（CLI over SSH / 本机 socket）、Cloudflare DNS |
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
devos/
|
||
├── apps/
|
||
│ ├── api/ # NestJS 模块化单体（/api/v1 + /api/v1/mcp）
|
||
│ └── web/ # React SPA（ProLayout）
|
||
├── packages/
|
||
│ ├── types/ # 共享领域类型
|
||
│ ├── auth/ # JWT(HS256) + 密码哈希（零第三方依赖）
|
||
│ ├── api-client/ # 浏览器 API 客户端
|
||
│ └── ui/ # 共享 UI（预留）
|
||
├── prisma/ # schema + migrations + seed
|
||
├── tests/ # bun test 单元测试
|
||
├── infra/ssh-target/ # 开发用 SSH 目标机（--profile dev-target）
|
||
├── docker-compose.yml
|
||
└── Docs/devos-v1/ # 规范文档（唯一事实源）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 基础设施（PostgreSQL 15432 / Redis 16379，避免与本机其它实例冲突）
|
||
docker compose up -d postgres redis
|
||
|
||
# 2. 安装依赖
|
||
bun install
|
||
|
||
# 3. 数据库迁移 + 种子（管理员账号来自 .env）
|
||
bunx prisma migrate deploy
|
||
bun run prisma/seed.ts
|
||
|
||
# 4. 构建
|
||
bun run build:packages
|
||
bun run build:api
|
||
bun run build:web
|
||
|
||
# 5. 启动 API（默认 :4100）
|
||
bun apps/api/dist/main.js
|
||
|
||
# 6. 开发前端（任一 dev server 端口，API 直连 :4100）
|
||
bun --hot apps/web/index.html
|
||
```
|
||
|
||
默认管理员：`admin@devos.local`，密码为部署时 `.env` 中 `SEED_ADMIN_PASSWORD` 的值（**不要使用示例值上线**；本实例已轮换为随机密码）。
|
||
|
||
## 环境变量（.env）
|
||
|
||
| 变量 | 说明 |
|
||
| --- | --- |
|
||
| `PORT` / `HOST` | API 监听（默认 4100 / 0.0.0.0） |
|
||
| `APP_SECRET` | JWT HS256 密钥（必填） |
|
||
| `ENCRYPTION_KEY` | 凭据信封加密主密钥，64 位 hex（必填） |
|
||
| `DATABASE_URL` | PostgreSQL 连接串（必填） |
|
||
| `REDIS_URL` | Redis（任务派发信号，可选降级） |
|
||
| `AI_PROVIDER_*` | OpenAI 兼容 AI Provider（可选；缺省用启发式规划器） |
|
||
|
||
## 功能地图（V1 = 15-ZCODE-DEV-SPEC 任务 001–018）
|
||
|
||
- **认证与租户**：注册/登录（HS256 JWT 12h）、工作区 + 成员 RBAC（OWNER/ADMIN/MEMBER/VIEWER）、workspace isolation 全层强制
|
||
- **统一资源**：`resources` 身份/状态 + 类型化领域表（servers/websites/domains/containers/deployments/monitors/credentials/automations/ai_runs）+ 关系图谱（resource_relations）
|
||
- **审计**：每个变更写 `audit_logs`（actor/workspace/action/risk/requestId，元数据自动脱敏）
|
||
- **服务器**：SSH 连通性探测、命令执行（危险命令 CRITICAL 标记）、重启（显式 confirm）、local provider（本机 docker socket）
|
||
- **Docker 发现**：容器 list/inspect/restart（SSH `docker` CLI 或 Engine API 双适配），容器入资源图谱（runs_container 关系）
|
||
- **网站与部署**：网站 CRUD + 关系；部署 = QUEUED→RUNNING→SUCCEEDED/FAILED 异步流水线（git 拉取 → docker build → 容器替换 → curl 健康验证），步骤级日志与进度、运行中取消（步骤间生效）
|
||
- **域名**：Cloudflare（token 凭据）与 MANUAL 双 provider；记录读取/写入/删除 + 审计
|
||
- **监控**：HTTP/TCP 检查调度器（interval），结果历史，`website.down` / `website.recovered` 事件
|
||
- **事件总线**：规范事件名（`deployment.success` 等），持久化 `events` + 进程内分发 + Redis PUBLISH
|
||
- **任务队列**：Postgres `jobs` 状态机（PENDING/RUNNING/…/DEAD）+ SKIP LOCKED 认领 + 指数退避 + 僵死回收 + Redis 派发信号
|
||
- **自动化**：Trigger（MANUAL/CRON/EVENT/WEBHOOK）→ Condition（path/op/value）→ Action（LOG/WEBHOOK/DEPLOY_WEBSITE），重试/超时/执行历史
|
||
- **AI Gateway**：objective → 计划（LLM 或启发式）→ 风险评估 →（HIGH/CRITICAL 需审批）→ 工具执行 → 领域验证 → 报告；工具层与 UI/MCP 共享同一授权与审计
|
||
- **MCP**：`POST /api/v1/mcp`（Streamable HTTP，无状态），Bearer JWT 鉴权，actorType=MCP 审计；工具 14 个（server/website/deployment/domain/automation）
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
bun test # 26 个用例：JWT（alg 混淆/过期/篡改）、cron、脱敏、危险命令、docker 输出解析、条件评估
|
||
```
|
||
|
||
## MCP 接入示例
|
||
|
||
```bash
|
||
curl -X POST http://localhost:4100/api/v1/mcp \
|
||
-H "Authorization: Bearer <JWT>" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept: application/json, text/event-stream" \
|
||
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
|
||
```
|
||
|
||
## 安全设计（11-SECURITY.md）
|
||
|
||
- 凭据 AES-256-GCM 信封加密，AAD 绑定 workspaceId；无任何明文读取端点
|
||
- 日志/审计/工具结果统一脱敏（键名+内嵌 token 模式）
|
||
- HIGH/CRITICAL 动作（部署、重启、凭据变更）需显式确认或审批
|
||
- MCP 不是绕过安全旁路：同 JWT、同授权、同审计
|
||
- API 错误契约：`{error:{code,message,requestId}}`，不暴露堆栈与机密
|
||
|
||
## AI 聊天（产品核心入口）
|
||
|
||
`/ai` 是对话式管理入口：用自然语言完成查询、创建任务/笔记、部署网站、重启容器、DNS 解析、URL 总结存笔记等**全部操作**。
|
||
|
||
- **双引擎**：配置 LLM（`AI_PROVIDER_*`）时走 OpenAI function-calling 多轮编排（工具白名单 29 个，覆盖增删改查与复合流程）；未配置时内置规则引擎，核心操作开箱可用
|
||
- **安全**：HIGH/CRITICAL 操作（部署/重启容器/删除）不直接执行，聊天中出审批卡片，确认后经 AiRun 管线执行；所有工具调用与人工/MCP 走同一授权与审计
|
||
- **验证**：以 Mock LLM（脚本化 function-calling）完成端到端验证 ——
|
||
「总结 <url> 保存到 Note」→ web.fetch + note.create ✓
|
||
「把 <github url> 安装到 JP-001 并用 xx.com 在 CF 代理解析」→ repository.createFromUrl + server.find + domain.find + website.create + domain.upsertRecord(proxied) ✓ + website.deploy 转审批 → 用户确认 → 部署 job 执行 ✓
|
||
|
||
## Notes AI 助手与配置
|
||
|
||
笔记页（`/notes`）为双栏笔记应用：TipTap 富文本（标题/列表/任务列表/代码块/引用 + 占位符 + 自动保存 1.2s）+ 置顶/标签/搜索 + AI 助手。
|
||
|
||
AI 助手动作：续写、总结要点、润色、中译英、英译中、生成大纲、起标题（选中文字后可只处理选区）。
|
||
|
||
启用 AI：在 `.env` 配置任意 OpenAI 兼容端点后重启：
|
||
|
||
```bash
|
||
AI_PROVIDER_BASE_URL=http://127.0.0.1:23030/openai/v1 # 示例：本机 claude-relay
|
||
AI_PROVIDER_API_KEY=<你的访问令牌>
|
||
AI_PROVIDER_MODEL=claude-sonnet-4-5
|
||
systemctl restart devos-api
|
||
```
|
||
|
||
未配置时 AI 菜单会明确提示，不影响其它功能。
|
||
|
||
## Phase 2 增量（Docs/devos-v1-phase2）
|
||
|
||
| 阶段 | 内容 | 状态 |
|
||
| --- | --- | --- |
|
||
| A 安全加固 | 生产 secret 校验、注册开关（`ENABLE_REGISTRATION`，生产默认关）、登录/注册限流、webhook HMAC+防重放、默认密码轮换、测试凭据清理、9 个安全回归测试 | ✅ |
|
||
| B 资源图谱 | 关系类型标准化（`RELATION_TYPES` 大写规范 + 数据迁移）、删除影响检查（`GET /resources/:id/relations/impact`）、项目页（Projects 聚合关系与活动） | ✅ |
|
||
| C 基础设施 | 服务器 stats（uptime/CPU/内存/磁盘/Top 进程）、Docker start/stop/logs/stats/images、Job Center（列表/详情/重试/取消） | ✅ |
|
||
| D 网站部署 | GitProviderConnection（GitHub/GitLab/Gitea 适配器）、Repository 聚合 + 凭据克隆（token 不进 URL/不残留 .git/config）、Website environment、部署 buildStrategy/deployStrategy/verification 记录 | ✅ |
|
||
| E 生产力 | Tasks（5 状态看板字段）、Notes（markdown+预览；TipTap 留待下迭代）、Certificates（TLS 探针+到期预警）；**Email 模块延后** | ✅（Email 延后） |
|
||
| F 自动化 | PATCH 编辑、HMAC webhook、新动作（CONTAINER_RESTART/TASK_CREATE/NOTE_CREATE/NOTIFICATION_SEND）+ 站内通知 | ✅ |
|
||
| G/H AI+MCP | 工具注册表扩至 18 个（task.list/create、note.create、container.restart 等）、启发式规划器新场景（故障诊断/任务记录/容器重启）、MCP 同步暴露 | ✅ |
|
||
| I 统一 UX | 全局搜索（`/search` + 头部入口 ⌘K 提示）、通知中心（铃铛+未读数）、任务中心页、项目页、主题切换（亮/暗） | ✅ |
|
||
|
||
新增 API 一览：`/git/*`、`/tasks`、`/notes`、`/certificates`、`/jobs`、`/search`、`/notifications`、`/automations/:id`(PATCH)、`/servers/:id/stats`、`/servers/:id/images`、`/containers/:id/start|stop|logs|stats`、`/resources/:id/relations/impact`。
|
||
|
||
## 生产部署（本机）
|
||
|
||
- systemd 常驻：`systemctl status devos-api`（/etc/systemd/system/devos-api.service，监听 127.0.0.1:4100，自动重启/开机自启）
|
||
- API 同进程托管 Web 静态资源与 SPA fallback（`apps/web/dist`），nginx 仅纯反代
|
||
- 域名：`ldns devos.opentest.cc 127.0.0.1:4100`（nginx 反代 + Cloudflare DNS/CDN）
|
||
- 线上地址：**https://devos.opentest.cc**
|
||
|
||
更新部署流程：
|
||
|
||
```bash
|
||
bun run build:api && bun run build:web && systemctl restart devos-api
|
||
```
|
||
|
||
## 已知限制（V1 范围内取舍）
|
||
|
||
- `bun --hot` dev server 下 ProComponents 存在 CJS 互操作问题（生产 bundle 与 nginx 部署不受影响）
|
||
- 登出为无状态（客户端丢弃 JWT）；撤销列表留待 V2
|
||
- Webhook 触发的自动化以 `X-Webhook-Secret` 头校验（HMAC 签名留待 V2）
|