devos/README.md

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

目录结构

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/    # 规范文档（唯一事实源）

快速开始

# 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）

测试

bun test   # 26 个用例：JWT（alg 混淆/过期/篡改）、cron、脱敏、危险命令、docker 输出解析、条件评估

MCP 接入示例

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）完成端到端验证 —— 「总结 保存到 Note」→ web.fetch + note.create ✓ 「把 安装到 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 兼容端点后重启：

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

更新部署流程：

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）