标准部署架构
项目通过资源配置、Secret 引用和固定版本镜像部署。支持 Windows + WSL2、Linux 和兼容 Docker 的服务器。
标准 Docker 完成口径
- 固定版本 Dockerfile/镜像与现实的少量 compose 组合。
- 统一无秘密项目资源模板；只出现 Secret 引用或受控 secrets 注入。
- 命名 volume/数据目录、健康检查、stdout/stderr 日志和长期服务恢复策略。
- 配置校验、deploy、doctor/health、accept、backup、restore、upgrade、rollback 都有标准命令。
- 同一套配置不写死宿主机路径，适用于 Windows + WSL2、常规 Linux 和兼容 Docker 环境。
- 逻辑模块可共进程；只有真实隔离、扩缩或安全需要时才拆容器。
部署入口
deploy/standard 用于中心和项目全链路验收；deploy/project 用于新项目，只部署所选的 Robot、Project Intelligence 和 Test Runtime。
已完成标准化门禁
统一 Docker Compose 已在 devbox 完成干净部署、健康检查、重启恢复、正式固定版本升级、加密备份恢复和回滚；Server 0.16.0 与 Management 0.4.0 还完成了线上原版超集验收。旧 Server 0.15.0 回滚必须同时恢复升级前 Schema 16 快照，禁止让旧二进制读取 Schema 17。v2 Release 可选择受 repository allowlist 约束的 OCI digest Provider，也可由 Generic Package 按内容摘要只取缺失层、断点续传并自动回退完整包。
统一 Distribution Provider
- Generic Package：优先校验内容目录、复用缓存、Range 续传并只取缺失层；逐层/重组摘要失败时自动下载同版本完整归档，双重失败在替换前关闭。
- OCI：只接受 allowlist 内的完整 repository@sha256 digest，通过相同隔离 Docker Proxy 拉取。
- 两种 Provider 共用 managed-deployment-release/v2、中心确认与权限、Controller 替换、健康门禁、结果和回滚；legacy v1 与无内容描述的 v2 Package 继续兼容。
- Registry Auth 只来自同一个 deployment_registry_auth Secret，不进入 Release、命令、日志或证据。
部署原则
- 所有顶层组件都声明一种交付策略：独立服务、随宿主嵌入、构建产物、CI 作业或尚未标准化。
- Release Unit 是一次构建、安装、升级和回退的不可变交付物；它可以承载多个独立逻辑模块。
- 密钥和环境配置不进入 Git、镜像或公开文档。
- 运行数据与镜像/代码分离。
- 部署后必须执行健康检查和触通完整功能分支的验收。
- 不可逆迁移必须有明确恢复方案。
统一验收证据
Deployment Acceptance Record 是目标机输出的无凭据版本化证据，统一使用 AI-DEPLOY- executionId。Robot、Project Intelligence、Server、Management 与 Test Runtime 的版本化发布包均携带 accept-host；平台命令再执行 validate、summary 与 Release Unit gate。自动检查和人工检查分开记录，仍有 manual-required 时只能是 automated-passed；Profile 不完整、发布标识不一致或清单强制人工检查缺失都会拒绝放行。Test Runtime 按 Worker、Intake、Writeback 分别记录，Test MCP 不伪装成常驻服务。
Robot 主路径
标准 Compose 以固定 Robot Base/App 镜像运行 PostgreSQL、迁移、API、Worker、Dispatcher 和 Scheduler；通道与 PI 都是显式可选 profile。devbox 已验证迁移、ready、Worker/Outbox、媒体信封、重启和卷恢复；企微长连接与飞书成熟使用事实已用 existing-evidence 和当前部署证据合并验收。
Project Intelligence 主路径
项目智能节点复用 Robot App digest，但作为单独可选 profile 只发起出站连接，项目目录和 verifier 公钥只读挂载，审计写入命名卷。devbox 已验证 Server 注册、远程资源/Expert 契约、网络与重启；真实端侧直接工具与两个 Cursor Subagent 的并行、续聊和失败隔离也已通过 live。
Test Runtime 主路径
Intake、Worker、DevOps Writeback 继续独立，Test MCP 由 Worker 启动；既有签名 Worker→MCP、隔离造数与专用 DevOps 写回证据保留。test-observe 的私有共享 Provider、外部 Tester live、OBSERVE 31 项门禁，以及 Runner 的本机 live + devbox Compose 同响应 shadow 均已通过。旧 Runner 工具继续兼容。
Management Runtime 主路径
Registry 与 Server 使用固定平台镜像、Docker Secret、命名卷、健康检查和回滚状态；当前 devbox 已验证不同组织主体创建/发布、服务端确认、审计、重启恢复、实际 Server 签名快照消费与篡改拒绝。实时 IdP 同步、资源级 ABAC 与公网 TLS 仍按独立产品/目标机检查推进。
Server Runtime 主路径
Server、CLI 与共享运行包位于固定平台镜像，Secret 只在启动时投影，数据进入命名卷；devbox 已验证协议、认证、任务、重启、备份恢复、升级和回滚。目标主机不需要安装 Node、Python 或 Monorepo 依赖。
统一操作入口
- npm run deployment -- list：查看全部组件的交付策略。
- npm run deployment -- units：查看不可变 Release Unit 及其目标 Profile。
- npm run deployment -- show <component>：解析唯一默认 Profile。
- npm run deployment -- doctor <component>：离线验证配置样例与仓库证据。
- npm run deployment -- plan <component>：生成准备、配置、备份、部署、验收、升级和回退清单。
- npm run deployment -- acceptance validate|summary|gate：验证目标机记录、生成归档摘要，并按发布单元执行最终放行门。
持续验证与发布产物
GitLab CI 在分支、合并请求和 Tag 上强制运行架构清单、目录结构、品牌、敏感数据、路由、兼容性和文档构建检查。正式 Tag 还会从干净 commit 构建并隔离演练 Server、Management 与 Test Runtime 归档，保存归档和 SHA-256。
Robot 与 Project Intelligence 的正式产物必须在具备 Docker Buildx、Registry 写权限和精确工具版本的受保护 Linux Runner 上构建。仓库已具备发布器、digest 门禁和结构测试，但该 Runner 尚未建立实际成功证据，因此不能宣称自动发布已经完成。
公开路由门禁
正式文档站继续使用与现有业务服务隔离的 Sites 托管 origin。若未来启用自定义域名，必须先由运维确认 DNS、TLS 与路径 Owner，再运行 npm run check:routing；同源路径重叠或未经授权触碰生产路径会被拒绝。
当前发布复用既有 project_id 和正式 Sites 地址，不创建重复站点，也不修改 Server、Robot 或现有反向代理。自定义域名是非阻塞增强。
公开与内部
公共站只展示通用拓扑和无敏感配置。真实域名、IP、项目路径、账号和应急联系方式属于内部 Runbook。
发布门禁
未声明内容默认属于 internal。公开站只从 documentation.manifest.json 同步明确授权的 public JSON 事实源，并拒绝真实业务 origin 与本机绝对路径。
机器清单中的 Release Unit
一个发布单元可以包含多个组件。Test Runtime 一次发布，Worker、Intake 和 Writeback 分别记录部署与人工验收结果。
Robot Release Bundle
digest-pinned-compose-archive；一次构建、安装、升级和回滚，组件职责与数据归属仍保持独立。
robot-release · robot-production-standard查看发布与放行契约
发布配方
- release/robot-runtime.manifest.json
- npm run release:robot -- --image-lock <robot-images.json> --output <release.tar.gz>
- npm run rehearse:robot -- <release.tar.gz>
目标机记录
- sh bin/accept-host | tee host-acceptance.jsonl
- 统一 validate / summary / gate 后才可归档放行
目标 Profile
必需人工检查
- robot-production-standard · channel-round-trip
Project Intelligence Release Bundle
digest-pinned-compose-archive；一次构建、安装、升级和回滚，组件职责与数据归属仍保持独立。
project-intelligence-release · project-intelligence-node-standard查看发布与放行契约
发布配方
- release/project-intelligence-runtime.manifest.json
- npm run release:project-intelligence -- --image-lock <robot-images.json> --output <release.tar.gz>
- npm run rehearse:project-intelligence -- <release.tar.gz>
目标机记录
- sh bin/accept-host | tee host-acceptance.jsonl
- 统一 validate / summary / gate 后才可归档放行
目标 Profile
必需人工检查
- project-intelligence-node-standard · server-registration
Server Runtime
self-contained-node-archive；一次构建、安装、升级和回滚，组件职责与数据归属仍保持独立。
server-runtime · server-production查看发布与放行契约
发布配方
- release/server-runtime.manifest.json
- npm run release:server-runtime -- <release.tar.gz>
- npm run rehearse:server-runtime -- <release.tar.gz>
目标机记录
- sh bin/accept-host | tee host-acceptance.jsonl
- 统一 validate / summary / gate 后才可归档放行
目标 Profile
必需人工检查
- server-production · tls-proxy
- server-production · authenticated-read-fixture
Management Runtime
self-contained-node-archive；一次构建、安装、升级和回滚，组件职责与数据归属仍保持独立。
management-runtime · management-registry-standard查看发布与放行契约
发布配方
- release/management-runtime.manifest.json
- npm run release:management-runtime -- <release.tar.gz>
- npm run rehearse:management-runtime -- <release.tar.gz>
目标机记录
- sh bin/accept-host | tee host-acceptance.jsonl
- 统一 validate / summary / gate 后才可归档放行
目标 Profile
必需人工检查
- management-registry-standard · signed-snapshot-server-consumption
- management-registry-standard · tls-proxy
Test Runtime
multi-module-node-archive；一次构建、安装、升级和回滚，组件职责与数据归属仍保持独立。
test-runtime · test-worker-standard / test-intake-standard / test-writeback-standard查看发布与放行契约
发布配方
- release/test-runtime.manifest.json
- npm run release:test-runtime -- <release.tar.gz>
- npm run rehearse:test-runtime -- <release.tar.gz>
目标机记录
- sh bin/accept-host | tee host-acceptance.jsonl
- 统一 validate / summary / gate 后才可归档放行
目标 Profile
必需人工检查
- test-worker-standard · project-driver-smoke
- test-worker-standard · server-queue-round-trip
- test-intake-standard · live-iteration-read
- test-writeback-standard · authorized-project-writeback
机器清单中的部署 Profile
以下 Profile 来自部署清单。新环境使用默认 Profile；可选 Profile 的适用条件见各条目说明。
标准生产部署
长期运行、可独立扩缩、可观测和可回滚的正式环境
robot-production-standard · robot · docker-compose-v2 · postgres / migrate / api / worker / dispatcher / scheduler / listener-or-webhook / reverse-proxy / optional-admin / shared-runtime-state-ledger-on-named-data-volume查看完整部署契约
前置条件
- Linux production host
- Docker Engine 24+
- Docker Compose v2
- non-fixture digest-pinned Robot Release Bundle produced by the standard image publisher
- TLS reverse proxy or outbound long connection
- external secret storage
配置与交付物
- apps/robot/.env.example
- apps/robot/schemas/deployment-config.schema.json
- apps/robot/config/bots.example.yaml
- apps/robot/config/qiyeweix.example.yaml
- apps/robot/config/qiyeweix-long.example.yaml
- apps/robot/config/qiyeweix-relay.example.yaml
- apps/robot/config/test-environments.example.yaml
- apps/robot/config/database-access.example.yaml
- apps/robot/config/elasticsearch-access.example.yaml
- apps/robot/schemas/runtime-settings.schema.json
- apps/robot/schemas/qiyeweix-relay-config.schema.json
- apps/robot/schemas/qiyeweix-long-config.schema.json
- apps/robot/schemas/qiyeweix-public-relay-config.schema.json
- apps/robot/schemas/test-environments-config.schema.json
- apps/robot/schemas/database-access-config.schema.json
- apps/robot/schemas/elasticsearch-access-config.schema.json
- apps/robot/zcy-mcp/.env.example
健康与验收
- Robot Release Bundle integrity rehearsal
- sh bin/accept-host
- minimal channel round-trip
- doctor reports Runtime state ledger ready when shadow/standard is enabled
备份范围
- PostgreSQL logical backup
- project/config backup without secrets
- append-only Runtime state ledger when shadow/standard is enabled
- workspace/index cache is rebuildable
install and rehearse a digest-pinned immutable bundle, pull without building, back up PostgreSQL, the Runtime state ledger and external configuration, run compatible migrations, atomically switch current, start with --no-build, then verify doctor, ready and business smoke test
switch current to the previous digest-pinned bundle and restore the pre-migration PostgreSQL backup when required; preserve project data, model homes, outbox, Runtime state ledger and named volumes; legacy rollback ignores but does not delete the ledger
紧凑部署
资源受限的试点或小型团队环境，不作为默认生产路径
robot-compact · robot · docker-compose-v2 · core-with-postgres-and-process-supervision / optional-admin查看完整部署契约
前置条件
- Docker Engine 24+
- Docker Compose v2
- explicit host-mounted data directories
配置与交付物
- apps/robot/.env.example
- apps/robot/all-in-one/compose.yaml
健康与验收
- all-in-one compose ps
- /health/ready
- migration and pgvector check
- worker smoke test
- compact-to-standard preview
备份范围
- host PostgreSQL directory plus logical dump
- core data directory
- credential home with restricted permissions
use all-in-one deploy script with running-job guard and health verification
immediate old-volume rollback only before new data; otherwise use the preview-first compact-to-standard migration with logical restore and snapshot comparison
开发环境
本地开发、单元测试和配置验证
robot-development · robot · python-node-docker · local virtualenv / local node packages / optional docker dependencies查看完整部署契约
前置条件
- Node.js 20+
- Python 3.11+
- Docker when testing compose
配置与交付物
- example files only
- local ignored environment files
健康与验收
- pytest
- npm test
- frontend build
- docker compose config --quiet
备份范围
- Git history for source and versioned configuration
- local ignored runtime data is disposable and must not be treated as a durable backup
not applicable
git worktree or branch rollback
项目智能标准节点
在可访问项目资源的环境中运行独立节点，通过出站 HTTPS 向 Server 提供有界项目证据
project-intelligence-node-standard · project-intelligence · docker-compose-v2 · one-node-process / outbound-https-relay / read-only-project-volumes / read-only-capability-verifier-key / persistent-capability-audit-ledger / persistent-runtime-state-ledger / local-rebuildable-indexes查看完整部署契约
前置条件
- Docker Engine 24+
- Docker Compose v2
- Flynor Server compatible relay
- read-only project/config mounts
- optional Server capability issuer plus node public-key-only verifier configuration
配置与交付物
- release/project-intelligence-runtime.manifest.json
- apps/robot/config/project-intelligence-node.env.example
- apps/robot/config/project-intelligence/bots.example.yaml
- apps/robot/config/project-intelligence/knowledge-selection.example.yaml
- apps/robot/schemas/project-intelligence-node.schema.json
健康与验收
- npm run rehearse:project-intelligence -- <release.tar.gz>
- sh bin/accept-host
- Flynor Server node status reports online
- signed mode reports signed-capability-lease and persists one allowed request while rejecting wrong scope/replay
- node check reports Runtime state ledger ready when shadow/standard is enabled
备份范围
- versioned non-secret project configuration
- append-only capability audit ledger when signed mode is enabled
- append-only Runtime state ledger when shadow/standard is enabled
- project source remains in its authoritative repositories
- local indexes and expert sessions are rebuildable
back up the capability and Runtime state ledgers, install a tested immutable Project Intelligence Release Bundle, atomically switch current, restart only its systemd unit, then verify doctor, ledger integrity and Server registration
atomically switch current to the previous protocol-compatible bundle and restart; preserve both ledgers, and let legacy versions ignore the Runtime state ledger; rebuild local indexes when required
固定测试环境执行服务
在固定可读写测试环境中逐项领取 Server 队列任务，执行项目 Driver/Test MCP 并回传证据化结果
test-worker-standard · test-worker · node-systemd · flynor-server-queue / one-worker-service / versioned-project-driver / stdio-test-mcp / persistent-artifact-directory查看完整部署契约
前置条件
- rehearsed self-contained Test Runtime archive
- Node.js 20+
- compatible Flynor Server
- dedicated non-login user
- fixed non-production test environment
- versioned project Driver and tool catalog
- external secret file
配置与交付物
- apps/test-worker/config/worker.example.json
- apps/test-worker/schemas/worker-config.schema.json
- apps/test-mcp/schemas/tools-config.schema.json
- /etc/flynor/test-worker.env
健康与验收
- sh bin/accept-host
- test-worker doctor
- Worker to Driver to Test MCP smoke
- Server test-executions-v1 capability
- one no-side-effect Server queue round-trip
- structured service log check
备份范围
- immutable source/package versions
- versioned non-secret Worker and tool configuration
- persistent execution evidence directory
- secret file through the approved secret-management process
stop new claims, wait for the active lease, deploy one tested compatible package set, run doctor/smoke, restart and verify one queue round-trip
restore the previous compatible Worker/Driver/MCP versions and config; never delete or overwrite existing AI- evidence directories
项目级待测试监听服务
按固定项目监听进行中迭代的待测试任务，排除受控任务树并以状态周期 executionId 幂等提交 Server；当前通过 Choerodon Adapter 兼容入口读取
test-intake-standard · test-intake · node-systemd · one-project-scoped-listener / embedded-choerodon-adapter-compatibility / flynor-server-intake-endpoint / persistent-cycle-ledger / outbound-https查看完整部署契约
前置条件
- rehearsed self-contained Test Runtime archive
- Node.js 20+
- compatible Flynor Server
- dedicated non-login user
- registered Choerodon project with active-iteration resolver
- dedicated read identity
- Server Token bound to exact intakeId and projectUnitId
- external secret file
- backed-up state directory
配置与交付物
- packages/integration-choerodon/config/test-intake.example.json
- packages/integration-choerodon/schemas/test-intake-config.schema.json
- /etc/flynor/choerodon-test-intake.env
- /etc/flynor/choerodon-projects.json
健康与验收
- sh bin/accept-host
- flynor-choerodon-test-intake doctor
- Server test-intake-v1 capability
- active-iteration and initial-data exclusion fixture
- one no-side-effect queue submission
- second scan produces no duplicate execution
- structured service log check
备份范围
- versioned non-secret listener configuration
- project registry
- persistent cycle ledger
- external credential file through the approved secret-management process
- Server-held execution queue
stop polling, back up the cycle ledger, deploy a protocol-compatible package, run doctor and fixture, restart and confirm the first scan reuses existing execution IDs
restore the previous compatible package, configuration and the same cycle ledger; never clear state to force a rescan
项目级 DevOps 测试回写服务
按固定项目逐项领取 Server 策略命令，将 AI 测试评论和允许的状态流转幂等写入外部 DevOps；当前通过 Choerodon Adapter 兼容入口写入猪齿鱼
test-writeback-standard · test-writeback · node-systemd · flynor-server-writeback-queue / one-project-scoped-connector / embedded-choerodon-adapter-compatibility / outbound-https查看完整部署契约
前置条件
- rehearsed self-contained Test Runtime archive
- Node.js 20+
- compatible Flynor Server
- dedicated non-login user
- registered Choerodon project
- dedicated Choerodon service identity
- Server Token bound to the exact connectorId and projectUnitId
- external secret file
配置与交付物
- packages/integration-choerodon/config/test-writeback.example.json
- packages/integration-choerodon/schemas/test-writeback-config.schema.json
- /etc/flynor/choerodon-test-writeback.env
- /etc/flynor/choerodon-projects.json
健康与验收
- sh bin/accept-host
- flynor-choerodon-test-writeback doctor
- test-writeback-v1 Server capability
- comment and transition fixture
- one no-side-effect queue receipt round-trip
- structured service log check
备份范围
- versioned non-secret connector configuration
- project registry
- external credential file through the approved secret-management process
- Server-held commands and receipts
stop new claims, wait for the active lease, deploy a protocol-compatible package, run doctor and fixture, restart and verify one queue receipt
restore the previous compatible package and config; execution markers and current-status checks must prevent duplicate external writes after redelivery
Management Registry 标准部署
提供版本化项目、能力、流程与策略定义的唯一正式事实源；管理演示页和 MCP 不保存第二份主状态
management-registry-standard · management · self-contained-node-systemd-reverse-proxy · immutable-release-directory / atomic-current-link / loopback-node-service / systemd / tls-reverse-proxy / persistent-registry-file / same-origin-confirmed-write-console / server-enforced-confirmed-write / organization-principal-directory / operation-rbac / distinct-human-author-publisher / ed25519-signed-snapshot / read-only-management-mcp-adapter查看完整部署契约
前置条件
- rehearsed self-contained Management Runtime archive
- Node.js 20+
- dedicated flynor-management non-login user distinct from Server
- TLS reverse proxy
- non-secret versioned organization principal directory with immutable subjectRef
- external reader, author, publisher and operator tokens
- external Ed25519 signing key
- persistent data directory
- read-only runtime artifact group when co-located
配置与交付物
- release/management-runtime.manifest.json
- apps/management/config/registry.example.json
- apps/management/config/principals.example.json
- apps/management/schemas/registry-config.schema.json
- apps/management/schemas/management-principals.schema.json
- /etc/flynor/management-registry.json
- /etc/flynor/management-registry.env
- /etc/flynor/management-snapshot.key
- /var/lib/flynor/management-releases/management-snapshot.json
健康与验收
- isolated Management Runtime release rehearsal
- sh bin/accept-host
- management registry doctor
- systemd active
- /health/live
- /health/ready
- Console permission projection, explicit confirmation and optimistic revision markers
- HTTP server-enforced confirmation
- operation RBAC and service-principal definition-write denial
- distinct human Author create and Publisher publish fixture
- reader sees published definitions only
- signed snapshot generation and verification fixture
- management MCP read fixture
备份范围
- immutable release archives and source commit
- persistent registry data file
- automatic pre-migration backup
- last verified signed snapshot and public key
- versioned non-secret configuration
- external secret and signing key through the approved secret-management process
install and rehearse an immutable compatible archive, stop Console writes, back up registry data, atomically switch current, run explicit migrate and doctor, restart, verify revision and Admin/Reader projections, regenerate the signed snapshot, then verify Server consumption
switch current to the previous compatible immutable release and restore the pre-migration registry backup when required; restore the last verified .previous snapshot when only publication is wrong; never point old code at newer unsupported state
Server 标准生产部署
轻量运行中枢，强制回环监听并由受控代理终止 TLS
server-production · server · self-contained-node-systemd-reverse-proxy · immutable-release-directory / atomic-current-link / loopback-node-service / systemd / tls-reverse-proxy / persistent-data-directory / verified-local-management-snapshot查看完整部署契约
前置条件
- Node.js 20+
- rehearsed self-contained Server Runtime archive
- dedicated non-login user
- TLS reverse proxy
- external secret file
配置与交付物
- infra/server/server.env.example
- /etc/flynor/server.env
- /var/lib/flynor/management-releases/management-snapshot.json
- /etc/flynor/management-snapshot.pub
- infra/server/flynor-server.service
- infra/server/nginx.conf.example
健康与验收
- isolated Server Runtime release rehearsal
- sh bin/accept-host
- systemd active
- loopback listener
- HTTPS diagnostic check
- Management snapshot ready or explicitly disabled
- authenticated published-definition read fixture
备份范围
- persistent data directory
- verified Management snapshot and public key
- external environment file through secret-management process
install and rehearse an immutable compatible archive, back up persistent data and external configuration, atomically switch current, restart, then verify storage schema, protocol compatibility, diagnostics, Management snapshot and authenticated fixtures
atomically switch current to the previous compatible immutable release and restore the pre-upgrade data backup when a migration is not backward compatible; restore the last verified Management .previous snapshot when only publication is wrong
文档站托管部署
公开产品与技术文档；内部运维内容必须独立受控
docs-site-hosted · docs-site · cloudflare-worker-compatible-site · static-assets / server-rendered-routes / existing-domain-route查看完整部署契约
前置条件
- validated build
- approved public origin/path
- no secret or internal topology content
配置与交付物
- apps/docs-site/.openai/hosting.json
- architecture/public-origins.manifest.json
健康与验收
- build success
- root route
- representative component route
- governance route
- broken-link validation
备份范围
- Git history and versioned architecture manifests
publish immutable version then switch deployment
redeploy previous immutable site version