# https://github.com/appaloft/appaloft 项目说明书
生成时间：2026-07-26 07:42:57 UTC
## 目录
- [项目概览](#page-1)
- [系统架构与仓库结构](#page-2)
- [核心功能：部署、沙箱与代理工作区](#page-3)
- [数据管理与持久化](#page-4)
- [前端与 Web 控制台](#page-5)
- [命令行、HTTP API 与 MCP/AI 技能入口](#page-6)
- [部署、自托管与基础设施](#page-7)
- [扩展性：插件、提供商与蓝图](#page-8)
## 项目概览
### 相关页面
相关主题：[系统架构与仓库结构](#page-2), [核心功能：部署、沙箱与代理工作区](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/appaloft/appaloft/blob/main/README.md)
- [README.zh-CN.md](https://github.com/appaloft/appaloft/blob/main/README.zh-CN.md)
- [DESIGN.md](https://github.com/appaloft/appaloft/blob/main/DESIGN.md)
- [docs/PRODUCT_ROADMAP.md](https://github.com/appaloft/appaloft/blob/main/docs/PRODUCT_ROADMAP.md)
- [docs/INSTALL.md](https://github.com/appaloft/appaloft/blob/main/docs/INSTALL.md)
- [docs/CHANGELOG.md](https://github.com/appaloft/appaloft/blob/main/docs/CHANGELOG.md)
- [install.sh](https://github.com/appaloft/appaloft/blob/main/install.sh)
- [docker-compose.yml](https://github.com/appaloft/appaloft/blob/main/docker-compose.yml)
- [packages/deploy/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/deploy/src/index.ts)
- [packages/sandbox/src/runner.ts](https://github.com/appaloft/appaloft/blob/main/packages/sandbox/src/runner.ts)
- [packages/secrets/src/control-plane.ts](https://github.com/appaloft/appaloft/blob/main/packages/secrets/src/control-plane.ts)
# 项目概览
Appaloft 是一个面向现代化应用与代理（agent）工作负载的部署平台，致力于以零配置的方式完成从代码到运行环境的全链路交付。本页基于仓库源码梳理项目的定位、核心模块、安装方式与版本演进，便于新成员快速建立全局认知。
## 一、项目定位与设计目标
Appaloft 的核心目标是降低部署复杂度，让开发者在不编写复杂编排文件的前提下完成应用上线。仓库根目录的 `README.md` 将其定位为「a stable release of the Appaloft deployment platform」，强调稳定、可重复、零配置三大特征。`DESIGN.md` 进一步指出，平台围绕「控制面（control-plane）」与「执行面（runtime）」分离的架构展开，控制面负责规划、调度与密钥管理，执行面负责在沙箱中拉起并运行用户负载。
零配置是贯穿整个平台的设计原则。`packages/deploy/src/index.ts` 中的 `planDeployment` 函数会在缺少显式配置时自动推断构建命令、运行时端口与资源规格，避免强制要求用户提供 `appaloft.yaml`。这种推断能力在 v1.3.0 中得到进一步增强，CHANGELOG 描述为「broaden zero-config planning」(`#789`)，覆盖更多语言与框架。
## 二、核心模块概览
Appaloft 的代码在 `packages/` 目录下以模块化方式组织，主要包含三大子系统：
- **deploy（部署规划）**：负责将仓库内容转换为可执行计划。`planDeployment` 是其入口，会调用语言检测器、构建器选择器与端口推断器协同工作。资料来源：[packages/deploy/src/index.ts:1-80]()
- **sandbox（沙箱执行）**：在隔离环境中真正运行代理或服务。`runner.ts` 中的 `runAgent` 会以流式事件（stream events）的形式回报执行进度，v1.3.0 起这一能力被进一步开放为 `streamAgentRunEvents` (`#795`)。资料来源：[packages/sandbox/src/runner.ts:1-60]()
- **secrets（密钥管理）**：处理控制面的密钥解密与轮换。`control-plane.ts` 实现了「fail-closed」策略：当解密或轮换无法安全完成时拒绝继续操作，这是 v1.0.2 中引入的安全修复 (`#687`)。资料来源：[packages/secrets/src/control-plane.ts:1-50]()
下表给出三大模块的职责对照：
| 模块 | 主要职责 | 关键入口 | 安全策略 |
|------|----------|----------|----------|
| deploy | 零配置规划、构建编排 | `planDeployment` | 配置最小权限原则 |
| sandbox | 隔离执行、事件流 | `runAgent` | 沙箱边界 + 流式可观测 |
| secrets | 密钥解密与轮换 | `rotateKey` | 解密失败即 fail-closed |
## 三、安装与运行方式
Appaloft 提供两种主要安装路径，二者均受官方发布流程统一管理。`docs/INSTALL.md` 与 `install.sh` 描述了脚本安装方式，而 `docker-compose.yml` 则定义了容器化部署方式。
脚本安装支持默认版本与显式版本：
```bash
curl -fsSL https://appaloft.com/install.sh | sudo sh
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2
```
容器化部署通过 GHCR 拉取官方镜像：
```bash
docker pull ghcr.io/appaloft/appaloft:1.3.2
docker pull ghcr.io/appaloft/appaloft:v1.3.2
```
`docker-compose.yml` 将控制面、执行面与可选的对象存储编排为一个最小可运行栈，端口与卷挂载均提供默认值，开发者只需执行 `docker compose up -d` 即可获得完整平台。资料来源：[docker-compose.yml:1-40]()
## 四、版本演进与社区关注点
自 v1.0.0 起，Appaloft 经历了快速迭代，主要里程碑可从 `docs/CHANGELOG.md` 与各 GitHub Release 中获取：
- **v1.0.0 – v1.0.4**：完成平台基础能力搭建，连续四个补丁版本聚焦稳定性与边界修复。
- **v1.0.2**：引入 `secrets` 的 fail-closed 行为，是社区最关注的安全改进之一 (`#687`)。
- **v1.1.0 – v1.2.0**：扩展部署能力并完善沙箱执行语义。
- **v1.3.0**：拓宽零配置规划覆盖范围 (`#789`)，并开放代理运行事件流 (`#795`)。
- **v1.3.1 – v1.3.2**：当前稳定线，CHANGELOG 显示为连续的稳定性发布。
社区讨论中频繁出现的主题包括：零配置边界、密钥轮换的可观测性以及沙箱事件流的使用方式。`docs/PRODUCT_ROADMAP.md` 公开了后续规划，建议读者结合路线图与 CHANGELOG 共同评估升级时机。资料来源：[docs/PRODUCT_ROADMAP.md:1-30]()
## 五、架构总览
下图给出 Appaloft 的高层架构关系，描述请求从 CLI/UI 进入控制面，再分发到各执行沙箱的路径：
```mermaid
flowchart LR
A[CLI / Web UI] --> B[Control Plane]
B --> C[deploy 规划]
B --> D[secrets 密钥]
B --> E[sandbox 调度]
C --> F[构建产物]
E --> G[隔离沙箱]
G --> H[流式事件]
D --> B
```
该图强调控制面作为唯一可信中枢，所有跨模块的状态变更都需经其审计；沙箱仅承载运行时负载，不会直接持有长期密钥，这与 `secrets` 模块的 fail-closed 策略共同构成平台的安全基线。
---
如需进一步深入，可阅读 `DESIGN.md` 中关于控制面状态机与沙箱生命周期的章节，或查看 `packages/` 下各模块的测试用例以了解具体行为约束。
---
## 系统架构与仓库结构
### 相关页面
相关主题：[数据管理与持久化](#page-4), [命令行、HTTP API 与 MCP/AI 技能入口](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/ARCHITECTURE.md](https://github.com/appaloft/appaloft/blob/main/docs/ARCHITECTURE.md)
- [docs/DOMAIN_MODEL.md](https://github.com/appaloft/appaloft/blob/main/docs/DOMAIN_MODEL.md)
- [docs/adr/0001-use-turborepo.md](https://github.com/appaloft/appaloft/blob/main/docs/adr/0001-use-turborepo.md)
- [docs/adr/0002-use-elysia.md](https://github.com/appaloft/appaloft/blob/main/docs/adr/0002-use-elysia.md)
- [docs/adr/0003-use-tsyringe.md](https://github.com/appaloft/appaloft/blob/main/docs/adr/0003-use-tsyringe.md)
- [apps/shell/README.md](https://github.com/appaloft/appaloft/blob/main/apps/shell/README.md)
- [package.json](https://github.com/appaloft/appaloft/blob/main/package.json)
- [turbo.json](https://github.com/appaloft/appaloft/blob/main/turbo.json)
# 系统架构与仓库结构
Appaloft 是一个面向生产环境的应用部署平台,提供从零配置(zero-config)规划、容器化运行时到沙箱(agent sandbox)事件流的一体化能力。整个仓库以**单仓多包(monorepo)** 形式组织,围绕 TypeScript 生态构建,后端服务、CLI、前端 shell 与共享领域模型共存于同一棵源码树,以保证控制平面(control-plane)与各端点间的类型一致性与发布节奏统一。资料来源:[docs/ARCHITECTURE.md:1-40]()
## 设计目标与适用范围
平台的核心设计目标是:**让一次部署行为可被完整描述、可被回放、可被审计**。围绕此目标,架构文档将系统划分为若干互相正交的子系统,主要包含:
- **deploy**:负责 zero-config 规划(基于源码自动推断运行时栈、端口与依赖)。
- **sandbox**:负责执行 agent run,并以流式事件(streams agent run events)回传过程状态。
- **secrets**:负责控制面密钥的解密与轮换,采用 *fail-closed* 语义,在任何不能安全完成的环节主动拒绝请求。
- **shell**:面向操作员与终端用户的 CLI/交互外壳。
资料来源:[docs/ARCHITECTURE.md:10-60](),[docs/DOMAIN_MODEL.md:1-35]()
## 仓库拓扑
仓库根目录由 `package.json` 与 `turbo.json` 共同驱动,采用 Turborepo 进行任务编排与缓存管理。`package.json` 中通过 `workspaces` 字段声明包集合,典型结构如下:
```text
.
├── apps/ # 可独立发布的应用
│ ├── shell/ # 操作员外壳
│ ├── control-plane/ # 控制平面服务
│ └── sandbox/ # 沙箱运行时
├── packages/ # 共享库与领域模型
│ ├── domain/ # 领域实体与不变量
│ ├── deploy/ # zero-config 规划引擎
│ └── secrets/ # 密钥管理
├── docs/
│ ├── ARCHITECTURE.md
│ ├── DOMAIN_MODEL.md
│ └── adr/ # 架构决策记录
└── turbo.json
```
各子包之间通过 TypeScript project references 互相引用,变更触发由 `turbo.json` 中的管道任务(`build`、`test`、`lint`、`typecheck`)统一协调,避免在多包场景下出现"半构建"状态。资料来源:[package.json:1-40](),[turbo.json:1-30](),[docs/adr/0001-use-turborepo.md:1-30]()
## 后端技术栈选型
后端服务以 **Elysia** 作为 HTTP 框架,基于其基于标准 Web Fetch API 的轻量内核构建控制平面 API;依赖注入则统一使用 **tsyringe**,通过装饰器在路由处理器中按需注入用例(repository、use-case、policy),从而把"路由层"与"用例层"清晰解耦。这一选择记录于两份 ADR(架构决策记录)中:
- **ADR-0001**:在多端点(CLI、API、Shell)共享构建管道的场景下,Turborepo 比 Lerna/Nx 更契合 Appaloft 的发布粒度。资料来源:[docs/adr/0001-use-turborepo.md:5-25]()
- **ADR-0002**:Elysia 在端到端类型推断与 Bun/Node 双运行时支持上更贴近部署平台的运维要求。资料来源:[docs/adr/0002-use-elysia.md:5-30]()
- **ADR-0003**:tsyringe 通过 TypeScript 反射元数据实现零样板依赖注入,使沙箱事件流等长生命周期对象易于替换为测试替身。资料来源:[docs/adr/0003-use-tsyringe.md:5-30]()
## 系统分层与数据流
下面以分层视图描述一次典型请求在系统内部的走向,从前端 shell 提交部署意图开始,经过控制平面鉴权与 zero-config 规划,最终落入沙箱运行时并以事件流形式回送:
```mermaid
flowchart TD
User[操作员/用户] --> Shell[apps/shell]
Shell --> CP[control-plane
Elysia + tsyringe]
CP --> Sec[secrets
fail-closed]
CP --> Plan[deploy
zero-config planner]
Plan --> Sb[sandbox
agent runtime]
Sb -- 事件流 --> CP
CP -- 结果 --> Shell
```
领域模型(`packages/domain`)位于此分层的中轴,所有跨层数据交换都基于该包中定义的实体与不变量;`secrets` 子系统在密钥解密失败或轮换无法安全完成时**主动拒绝请求**(fail-closed),该语义是 v1.0.2 的安全修复核心。资料来源:[docs/ARCHITECTURE.md:40-90](),[docs/DOMAIN_MODEL.md:20-70]()
## 版本节奏与发布制品
平台以 *稳定版 + 语义化版本* 的方式发布,镜像通过 GitHub Container Registry 分发(`ghcr.io/appaloft/appaloft:` 与 `:v` 两套标签并存),安装脚本 `https://appaloft.com/install.sh` 支持 `--version` 参数锁定。截至 v1.3.2,平台已迭代过 zero-config 规划广度扩展(#789)与沙箱事件流(#795)等关键能力。资料来源:[package.json:1-20](),[apps/shell/README.md:1-25](),社区上下文:v1.3.0 release notes
> **阅读建议**:刚加入项目的开发者应先阅读 `docs/ARCHITECTURE.md` 与 `docs/DOMAIN_MODEL.md` 建立全局心智模型,再按需查阅 `docs/adr/*` 了解每项关键技术选型的权衡;日常开发则以 `apps/shell/README.md` 为入口体验 CLI 工作流。
---
## 核心功能：部署、沙箱与代理工作区
### 相关页面
相关主题：[前端与 Web 控制台](#page-5), [部署、自托管与基础设施](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/CORE_OPERATIONS.md](https://github.com/appaloft/appaloft/blob/main/docs/CORE_OPERATIONS.md)
- [docs/workflows/deployments.create.md](https://github.com/appaloft/appaloft/blob/main/docs/workflows/deployments.create.md)
- [docs/workflows/execution-sandbox.md](https://github.com/appaloft/appaloft/blob/main/docs/workflows/execution-sandbox.md)
- [docs/workflows/agent-workspace.md](https://github.com/appaloft/appaloft/blob/main/docs/workflows/agent-workspace.md)
- [docs/workflows/agent-task-run.md](https://github.com/appaloft/appaloft/blob/main/docs/workflows/agent-task-run.md)
- [packages/application/src/deployment-handlers.ts](https://github.com/appaloft/appaloft/blob/main/packages/application/src/deployment-handlers.ts)
# 核心功能：部署、沙箱与代理工作区
Appaloft 是一个面向控制平面（control plane）的部署平台，其核心能力围绕三条主线展开：**部署（Deployment）**、**执行沙箱（Execution Sandbox）** 与 **代理工作区（Agent Workspace）**。三者协同构成了从代码提交到代理任务运行的完整链路，是 v1.0.0 至 v1.3.2 各版本持续迭代的重点。资料来源：[docs/CORE_OPERATIONS.md:1-15]()
## 部署（Deployment）：零配置规划与控制平面编排
部署子系统负责把用户项目从源码状态转换为可运行的实例。v1.3.0 引入了"广覆盖的零配置规划"（broaden zero-config planning）能力（commit `2d6a2c4`），无需用户显式编写大量配置即可完成拓扑推断。部署请求进入 `application` 包后由 `deployment-handlers.ts` 中的处理函数接管，调用流程在 `docs/workflows/deployments.create.md` 中以流程图形式描述。资料来源：[docs/workflows/deployments.create.md:1-30](), [packages/application/src/deployment-handlers.ts:1-40]()
部署链路的关键属性：
- **零配置规划**：基于仓库结构自动选择运行时、构建器与依赖源。
- **控制平面安全门控**：v1.0.2 引入的"secrets: fail closed"机制保证当控制平面的秘密（secret）解密或密钥轮换失败时，部署会主动拒绝继续推进而非降级放行，提交哈希 `4c1b0c5` 记录了此修复。资料来源：[v1.0.2 Release Notes]()
- **版本边界保护**：v1.0.3 修复了 release-please 的版本边界回归（commit `9d6c1b9`），避免错误版本被发布。
## 执行沙箱（Execution Sandbox）：隔离执行与事件流
执行沙箱为代理（agent）和其他运行单元提供一次性、可丢弃、彼此隔离的执行环境。`docs/workflows/execution-sandbox.md` 描述了沙箱的生命周期：创建 → 注入上下文 → 启动代理运行 → 收集产物 → 销毁。v1.3.0 进一步新增了"stream agent run events"（commit 来自 PR #795），允许客户端以流式方式接收运行中事件而非轮询结果。资料来源：[docs/workflows/execution-sandbox.md:1-45](), [v1.3.0 Release Notes]()
沙箱的设计约束：
- **隔离性**：每次任务分配独立的执行上下文，避免跨任务污染。
- **可观测性**：运行事件以流式推送，便于上层 UI 与日志系统订阅。
- **失败关闭**：与部署层一致，密钥相关的失败也采用"fail closed"语义，确保不会泄漏未解密的状态。
## 代理工作区（Agent Workspace）与代理任务运行
代理工作区是代理赖以持久化状态、共享上下文与跨任务复用产物的逻辑空间，由 `docs/workflows/agent-workspace.md` 定义；具体的单次任务执行则记录于 `docs/workflows/agent-task-run.md`。两者的关系是：工作区承载长期资源，任务运行（task run）描述单次会话式执行。
```mermaid
flowchart LR
A[代码仓库] --> B[Deployment Handlers]
B --> C{零配置规划}
C --> D[Execution Sandbox]
D --> E[Agent Workspace]
E --> F[Agent Task Run]
F --> G[事件流]
G --> H[控制平面聚合]
```
资料来源：[docs/workflows/agent-workspace.md:1-30](), [docs/workflows/agent-task-run.md:1-30]()
工作区与任务运行的关键点：
- **工作区是代理的根目录等价物**，存储配置文件、缓存与中间产物。
- **任务运行受沙箱约束**，每次运行可获得新的隔离环境，但能挂载同一工作区。
- **安全策略贯穿始终**：secret 解密失败、密钥轮换失败等异常均被 fail closed 拦截。
## 协同与版本演进
三条主线在控制平面中形成"部署产生实例 → 沙箱执行任务 → 工作区沉淀状态"的闭环。迭代节奏方面：
| 版本 | 关键改进 |
| --- | --- |
| 1.0.2 | secret 解密/密钥轮换 fail closed |
| 1.0.3 | release-please 版本边界修复 |
| 1.3.0 | 零配置规划广覆盖 + 代理运行事件流 |
最新稳定版 **Appaloft 1.3.2** 已发布，可通过 `curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2` 安装，或拉取 `ghcr.io/appaloft/appaloft:1.3.2` 镜像。资料来源：[v1.3.2 Release Page]()
## 小结
部署、沙箱与代理工作区共同定义了 Appaloft 控制平面的核心能力域：部署负责把代码变成可寻址的运行单元，沙箱保证运行过程的隔离与可观测，工作区让代理拥有跨任务的持久上下文。三者皆受到统一的 fail closed 安全策略约束，并在 1.3.x 系列中得到持续增强。资料来源：[docs/CORE_OPERATIONS.md:30-60]()
---
## 数据管理与持久化
### 相关页面
相关主题：[系统架构与仓库结构](#page-2), [部署、自托管与基础设施](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/persistence/pg/src/db.ts](https://github.com/appaloft/appaloft/blob/main/packages/persistence/pg/src/db.ts)
- [packages/persistence/pg/src/schema.ts](https://github.com/appaloft/appaloft/blob/main/packages/persistence/pg/src/schema.ts)
- [packages/persistence/pg/src/migrations/001_initial.ts](https://github.com/appaloft/appaloft/blob/main/packages/persistence/pg/src/migrations/001_initial.ts)
- [packages/persistence/pg/src/control-plane-secret-rotation.ts](https://github.com/appaloft/appaloft/blob/main/packages/persistence/pg/src/control-plane-secret-rotation.ts)
- [docs/adr/0004-use-postgres-kysely.md](https://github.com/appaloft/appaloft/blob/main/docs/adr/0004-use-postgres-kysely.md)
- [docs/SECURITY.md](https://github.com/appaloft/appaloft/blob/main/docs/SECURITY.md)
# 数据管理与持久化
## 概述与设计目标
Appaloft 的「数据管理与持久化」子系统负责为部署平台提供统一的存储抽象，负责对控制面状态、部署记录、密钥材料等关键数据执行持久化、迁移与一致性保护。系统通过集中封装数据库连接、Schema 定义以及版本化迁移，向上层业务（部署、sandbox、零配置规划等模块）提供可复用的数据访问入口，避免在多个服务中重复实现底层持久化逻辑。资料来源：[docs/adr/0004-use-postgres-kysely.md:1-40]()
在选型上，项目采用 PostgreSQL 作为主存储引擎，并基于 Kysely（TypeScript Query Builder）构建类型安全的查询层。PostgreSQL 提供的事务隔离、约束与并发控制满足部署平台对强一致性的要求；Kysely 则通过编译期类型推断减少字段拼写错误，配合迁移脚本实现可控演进。资料来源：[docs/adr/0004-use-postgres-kysely.md:10-60]()
## 模块结构与分层
持久化层按照「连接管理 → Schema 注册 → 迁移执行 → 业务封装」的层次组织，整体依赖关系如下：资料来源：[packages/persistence/pg/src/db.ts:1-30](), [packages/persistence/pg/src/schema.ts:1-20]()
```mermaid
flowchart TD
A[业务服务：deploy / sandbox] --> B[db.ts：连接池与 Kysely 实例]
B --> C[schema.ts：类型化表结构]
C --> D[001_initial.ts：基础迁移]
B --> E[control-plane-secret-rotation.ts：密钥轮换]
D --> F[(PostgreSQL 主库)]
E --> F
```
`db.ts` 提供共享的 `Kysely` 实例与连接池配置，使上层模块无需关心连接生命周期；`schema.ts` 将数据库表映射为 TypeScript 接口，作为 Kysely 的强类型契约；迁移模块以有序脚本方式管理 Schema 演进；`control-plane-secret-rotation.ts` 专门处理控制面密钥轮换的失败安全逻辑。资料来源：[packages/persistence/pg/src/db.ts:20-80](), [packages/persistence/pg/src/control-plane-secret-rotation.ts:1-40]()
## Schema 管理与迁移流程
所有表结构与索引通过版本化迁移文件落地，初始迁移 `001_initial.ts` 定义了部署平台核心实体（如部署记录、版本、用户、环境等）。迁移按文件名升序执行，使数据库变更具备可重放、可审计的特性，避免在生产环境中直接修改 Schema。资料来源：[packages/persistence/pg/src/migrations/001_initial.ts:1-60]()
迁移执行流程：
1. 应用启动时读取 `migrations/` 目录中的迁移文件，建立已执行集合；
2. 对未执行脚本按顺序运行，并通过事务保证原子性；
3. 若任何迁移失败，回滚事务并阻止应用继续启动，避免半升级状态。资料来源：[packages/persistence/pg/src/migrations/001_initial.ts:40-90]()
`schema.ts` 中导出的类型被 Kysely 用于约束字段类型，确保业务查询始终与 Schema 同步。结合迁移脚本，开发者调整列结构后必须同时更新类型定义与迁移脚本，从而形成「Schema—Type—Migration」三元一致性约束。资料来源：[packages/persistence/pg/src/schema.ts:20-70]()
## 控制面密钥与安全策略
持久化层直接承担控制面密钥（control-plane secrets）的存取职责，因此对解密失败、密钥轮换等异常路径采取 **fail-closed** 策略：一旦解密或轮换无法在不破坏完整性的前提下完成，必须立即停止变更，防止旧密钥被绕过导致密钥状态处于不一致窗口。资料来源：[packages/persistence/pg/src/control-plane-secret-rotation.ts:30-90](), [docs/SECURITY.md:1-40]()
该项目 v1.0.2 修复项（commit `4c1b0c5`）即明确强化了「当控制面密钥解密或轮换无法安全完成时 fail closed」的语义，避免在轮换中途将敏感数据暴露到不一致状态。资料来源：[docs/SECURITY.md:10-50](), 社区上下文：`v1.0.2` 发布条目()
`db.ts` 内部对连接字符串、密钥类敏感字段均通过环境变量或专用 secret store 注入，不直接落到源码中。任何与 PostgreSQL 凭证相关的运维动作，都应在部署平台的「密钥轮换」流程内执行，并由持久化层统一记录审计日志。资料来源：[packages/persistence/pg/src/db.ts:30-70](), [docs/SECURITY.md:20-60]()
## 与上层特性的协同
持久化层为部署、sandbox、零配置规划等上层特性提供查询接口与事务能力：
- **deploy**：依赖持久化层记录部署计划与历史版本，使零配置规划结果可追溯；社区上下文：v1.3.0「broaden zero-config planning」条目。
- **sandbox**：在流式输出 agent 运行事件时（v1.3.0「stream agent run events」），持久化层负责保存事件元数据，保证断线后可重放。
- **版本管理与回滚**：通过迁移与 Schema 版本号控制升级窗口，配合「密钥轮换 fail-closed」保证升级期间控制面状态确定性。
资料来源：[packages/persistence/pg/src/db.ts:40-100](), [packages/persistence/pg/src/schema.ts:50-100](), 社区上下文：v1.3.0、`v1.0.2` 发布条目()
---
## 前端与 Web 控制台
### 相关页面
相关主题：[核心功能：部署、沙箱与代理工作区](#page-3), [命令行、HTTP API 与 MCP/AI 技能入口](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/web/src/routes/+layout.svelte](https://github.com/appaloft/appaloft/blob/main/apps/web/src/routes/+layout.svelte)
- [apps/web/src/routes/+page.svelte](https://github.com/appaloft/appaloft/blob/main/apps/web/src/routes/+page.svelte)
- [apps/web/src/lib/components/console/ConsoleShell.svelte](https://github.com/appaloft/appaloft/blob/main/apps/web/src/lib/components/console/ConsoleShell.svelte)
- [apps/web/src/lib/components/console/Sidebar.svelte](https://github.com/appaloft/appaloft/blob/main/apps/web/src/lib/components/console/Sidebar.svelte)
- [apps/web/src/lib/orpc.ts](https://github.com/appaloft/appaloft/blob/main/apps/web/src/lib/orpc.ts)
- [packages/ui/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/ui/src/index.ts)
- [packages/ui/src/button/Button.svelte](https://github.com/appaloft/appaloft/blob/main/packages/ui/src/button/Button.svelte)
- [apps/web/src/lib/stores/session.ts](https://github.com/appaloft/appaloft/blob/main/apps/web/src/lib/stores/session.ts)
- [docs/ux/paas-ui-redesign-proposal.md](https://github.com/appaloft/appaloft/blob/main/docs/ux/paas-ui-redesign-proposal.md)
- [apps/web/svelte.config.js](https://github.com/appaloft/appaloft/blob/main/apps/web/svelte.config.js)
# 前端与 Web 控制台
Appaloft 的 Web 控制台是部署平台面向使用者的图形化入口，基于 SvelteKit 构建，运行在 `apps/web` 工作区，并通过 oRPC 协议与控制平面进行类型安全的通信。本页说明控制台的整体定位、模块构成、客户端调用方式以及 UI 组件复用机制。
## 总体定位与运行形态
Web 控制台作为 Appaloft PaaS 的"驾驶舱"，承担三类核心职责：项目与部署对象的可视化编排、运行时事件（例如 sandbox 的智能体运行事件）的实时呈现、以及控制平面密钥（secrets）等敏感操作的受控入口。控制台默认随主服务一起分发，亦可作为独立 Docker 镜像 `ghcr.io/appaloft/appaloft:1.3.2` 拉取后由运维人员独立托管。
其工程边界由 `apps/web` 单包承载：路由结构遵循 SvelteKit 文件系统约定，全局壳层在 `+layout.svelte` 中注入，而 `+page.svelte` 负责首页落地页与登录态分支。资料来源：[apps/web/src/routes/+layout.svelte:1-40]()、资料来源：[apps/web/src/routes/+page.svelte:1-30]()。
## 控制台壳层与导航结构
控制台的视觉与交互骨架集中在 `apps/web/src/lib/components/console/` 目录。其中 `ConsoleShell.svelte` 作为顶层容器，组合了顶栏（包含会话信息、租户切换、暗色模式开关）和侧边栏，并基于当前路由决定内容区的渲染。资料来源：[apps/web/src/lib/components/console/ConsoleShell.svelte:1-60]()。
`Sidebar.svelte` 则依据会话角色动态生成导航项，覆盖应用、部署、沙箱、密钥、审计等主要域。其内部通过订阅路由 store 与权限 store 实现高亮与禁用态，确保未授权入口不会暴露给普通用户。资料来源：[apps/web/src/lib/components/console/Sidebar.svelte:1-80]()。
## 与控制平面的 RPC 桥接
Web 控制台并不直接拼装 HTTP 请求，而是通过 oRPC 客户端统一调用控制平面暴露的流程化接口。`apps/web/src/lib/orpc.ts` 中导出了一个经过鉴权注入与错误归一化的 `client`，页面组件只需像调用本地函数一样调用远端流程，例如 `client.deploys.plan(input)`、`client.sandbox.events.subscribe({ runId })`。资料来源：[apps/web/src/lib/orpc.ts:1-70]()。
这种设计带来两个直接收益：第一，类型在前后端共享，避免请求/响应字段漂移；第二，oRPC 的订阅原语天然契合 `v1.3.0` 起引入的"流式智能体运行事件"能力，前端可通过 `client.sandbox.events.subscribe` 在不刷新页面的情况下持续接收运行日志，相关能力在 v1.3.0 changelog 中被列为 `stream agent run events`。资料来源：[apps/web/src/lib/orpc.ts:40-70]()。
## 会话状态与 UI 组件复用
会话状态由 `apps/web/src/lib/stores/session.ts` 集中维护，包含当前租户、令牌有效期、刷新策略等字段；壳层与各业务页面均订阅该 store 以决定渲染分支。资料来源：[apps/web/src/lib/stores/session.ts:1-50]()。
视觉控件来自内部包 `@appaloft/ui`（`packages/ui/src/index.ts`），其入口统一再导出按钮、表格、对话框等基础组件，保证控制台与未来 CLI TUI、移动端复用同一套设计语言。例如 `packages/ui/src/button/Button.svelte` 暴露了统一的 `variant`、`loading`、`disabled` 语义。资料来源：[packages/ui/src/index.ts:1-30]()、资料来源：[packages/ui/src/button/Button.svelte:1-40]()。
## 模块关系总览
下面以一张表格概括前端各关键模块的职责，便于新成员快速建立心智模型。
| 模块路径 | 职责 | 关键依赖 |
| --- | --- | --- |
| `apps/web/src/routes/+layout.svelte` | 全局壳层、主题与会话注入 | `ConsoleShell`、`session` store |
| `apps/web/src/lib/components/console/ConsoleShell.svelte` | 顶栏 + 侧栏 + 内容区组合 | `Sidebar`、`@appaloft/ui` |
| `apps/web/src/lib/orpc.ts` | 控制平面 RPC 桥接、订阅通道 | `@orpc/client`、会话令牌 |
| `apps/web/src/lib/stores/session.ts` | 会话、租户、权限状态 | `localStorage`、oRPC 鉴权 |
| `packages/ui/src/index.ts` | 基础 UI 组件聚合导出 | 各 `*.svelte` 子模块 |
需要说明的是，UX 层面的中长期演进方向记录在 `docs/ux/paas-ui-redesign-proposal.md` 中，提案围绕"零配置部署规划"与"事件流可视化"展开，与 `v1.3.0` 中 `deploy: broaden zero-config planning`、`sandbox: stream agent run events` 两项特性形成设计—实现闭环。资料来源：[docs/ux/paas-ui-redesign-proposal.md:1-120]()。
综上，Appaloft 前端以 SvelteKit 为底座、以 oRPC 为通信契约、以 `@appaloft/ui` 为设计系统，构成了一个可独立演进、又与控制平面强类型耦合的 Web 控制台。
---
## 命令行、HTTP API 与 MCP/AI 技能入口
### 相关页面
相关主题：[系统架构与仓库结构](#page-2), [前端与 Web 控制台](#page-5)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/adapters/cli/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/adapters/cli/src/index.ts)
- [packages/adapters/http-elysia/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/adapters/http-elysia/src/index.ts)
- [packages/ai/mcp/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/ai/mcp/src/index.ts)
- [skills/appaloft/SKILL.md](https://github.com/appaloft/appaloft/blob/main/skills/appaloft/SKILL.md)
- [docs/agent/appaloft-mcp-server.md](https://github.com/appaloft/appaloft/blob/main/docs/agent/appaloft-mcp-server.md)
- [docs/agent/appaloft-skill.md](https://github.com/appaloft/appaloft/blob/main/docs/agent/appaloft-skill.md)
# 命令行、HTTP API 与 MCP/AI 技能入口
Appaloft 作为面向自托管与零配置部署的控制平面，向外暴露了三类一等入口：本地 `appaloft` 命令行（CLI）、基于 Elysia 的 HTTP API，以及面向 AI Agent 的 MCP 服务器与 Appaloft Skill。下文按这三条通道分别介绍其职责、调用形态与典型使用场景，便于开发者在脚本、CI 流水线、以及 IDE / Agent 客户端中复用同一套平台能力。
## 入口全景
三条入口共用同一套底层服务（部署计划、沙箱执行、密钥解析），只是在传输层与语义层做适配。CLI 面向运维交互与自动化脚本；HTTP API 提供 REST/JSON 接口以供外部系统集成；MCP / Skill 入口则把上述能力以结构化工具暴露给 LLM 与 AI Agent，从而支持自然语言驱动的部署与诊断。
| 入口 | 适配器包 | 适用客户端 | 鉴权与传输 |
| --- | --- | --- | --- |
| CLI | `packages/adapters/cli` | 终端、CI 脚本 | 本地 socket / 控制面令牌 |
| HTTP API | `packages/adapters/http-elysia` | 浏览器、外部服务 | Bearer / mTLS over HTTPS |
| MCP / Skill | `packages/ai/mcp`、`skills/appaloft` | AI Agent、IDE 插件 | MCP stdio / SSE |
## 命令行入口（CLI 适配器）
CLI 适配器位于 `packages/adapters/cli/src/index.ts`，是 Appaloft 在主机上注册 `appaloft` 可执行命令的实现入口。安装脚本 `https://appaloft.com/install.sh` 会把该命令写入 `$PATH`，并通过 `sudo sh -s -- --version ` 形式支持固定版本安装。
设计上 CLI 既负责本地控制平面守护进程的启停，也承载面向运维人员的子命令（如 `appaloft deploy`、`appaloft status`、`appaloft doctor`）。所有子命令最终调用核心包内的领域服务，从而保证 CLI 与 HTTP API 在行为层面一致。
```bash
# 安装最新稳定版
curl -fsSL https://appaloft.com/install.sh | sudo sh
# 固定版本安装（与 release 标签一致）
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2
# 镜像拉取
docker pull ghcr.io/appaloft/appaloft:1.3.2
```
## HTTP API 入口（Elysia 适配器）
HTTP 适配器位于 `packages/adapters/http-elysia/src/index.ts`，使用 Elysia 构建轻量、类型安全的 REST 接口，向控制台、反向代理以及第三方系统开放平台能力。它把底层领域能力封装为标准的 HTTP 资源，使前端控制台可以无差别地消费。
适配器在 v1.0.2 的安全更新中纳入了“控制面密钥解密或密钥轮换无法安全完成时 fail-closed”策略，确保任何对受保护资源的 HTTP 请求在解密失败时返回错误而非默认放行。资料来源：[v1.0.2 安全说明](https://github.com/appaloft/appaloft/releases/tag/v1.0.2)。
## MCP / AI 技能入口
MCP 服务器位于 `packages/ai/mcp/src/index.ts`，与 `skills/appaloft/SKILL.md` 共同构成面向 AI Agent 的入口。
MCP 服务器以 Model Context Protocol 的方式把 Appaloft 的部署、沙箱与诊断能力注册为结构化工具，使 Claude、Cursor 等兼容 MCP 的客户端可以直接调用。在 v1.3.0 中新增了 `sandbox: stream agent run events`，使得 MCP 客户端能够以流式方式接收 Agent 运行过程中的事件，而不必等待最终结果。资料来源：[v1.3.0 更新日志](https://github.com/appaloft/appaloft/releases/tag/v1.3.0)。
`skills/appaloft/SKILL.md` 则是面向通用 AI 助手（不依赖 MCP）的自然语言入口，文件中声明了 Agent 在何种场景下应当选择 Appaloft Skill、可以执行哪些动作、以及与 `appaloft-mcp-server` 的关系。配套文档 `docs/agent/appaloft-mcp-server.md` 与 `docs/agent/appaloft-skill.md` 分别给出 MCP 与 Skill 两种集成方式下的接入步骤、可用工具列表与安全注意事项。
## 选型建议
- 一次性运维、CI 流水线：优先 CLI，便于脚本化与版本钉死。
- 与现有平台前端、网关、监控系统集成：使用 HTTP API，注意携带控制面令牌并依赖 v1.0.2 引入的 fail-closed 密钥策略。
- 让 LLM/Agent 直接驱动部署与诊断：优先 MCP，可获得流式事件；若客户端不支持 MCP，则回退到 Appaloft Skill，按 `SKILL.md` 中的提示词模板执行。
---
## 部署、自托管与基础设施
### 相关页面
相关主题：[核心功能：部署、沙箱与代理工作区](#page-3), [扩展性：插件、提供商与蓝图](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- 资料来源： [install.sh](https://github.com/appaloft/appaloft/blob/main/install.sh)
- 资料来源： [Dockerfile](https://github.com/appaloft/appaloft/blob/main/Dockerfile)
- 资料来源： [docker-compose.selfhost.yml](https://github.com/appaloft/appaloft/blob/main/docker-compose.selfhost.yml)
- 资料来源： [packages/providers/edge-proxy-caddy/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/edge-proxy-caddy/src/index.ts)
- 资料来源： [packages/providers/certificate-acme/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/certificate-acme/src/index.ts)
- 资料来源： [packages/providers/generic-ssh/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/generic-ssh/src/index.ts)
summary>相关源码文件
以下源码文件用于生成本页说明：
- [install.sh](https://github.com/appaloft/appaloft/blob/main/install.sh)
- [Dockerfile](https://github.com/appaloft/appaloft/blob/main/Dockerfile)
- [docker-compose.selfhost.yml](https://github.com/appaloft/appaloft/blob/main/docker-compose.selfhost.yml)
- [packages/providers/edge-proxy-caddy/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/edge-proxy-caddy/src/index.ts)
- [packages/providers/certificate-acme/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/certificate-acme/src/index.ts)
- [packages/providers/generic-ssh/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/generic-ssh/src/index.ts)
# 部署、自托管与基础设施
Appaloft 是一个面向自托管场景的部署平台，核心目标是把零配置部署规划、容器化控制面、边缘代理与证书生命周期管理整合到同一套基础设施中。本页围绕官方安装路径、容器镜像、自托管编排以及关键 Provider（边缘代理 / 证书 / SSH 部署）展开说明，涵盖从一键安装到面向公网暴露的完整链路。
## 安装与版本管理
平台提供两条主要安装路径：安装脚本与容器镜像，二者在版本标签上保持一致，便于混合部署。
```bash
# 通过官方安装脚本安装最新版
curl -fsSL https://appaloft.com/install.sh | sudo sh
# 锁定到指定版本
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2
# 拉取容器镜像
docker pull ghcr.io/appaloft/appaloft:1.3.2
docker pull ghcr.io/appaloft/appaloft:v1.3.2
```
`install.sh` 的职责是检测宿主机环境、拉取控制面二进制并完成 systemd / OpenRC 服务接入；同时支持 `--version` 参数以便在升级或回滚时锚定确切版本。资料来源：[install.sh:1-40]()
Docker 镜像路径通过 `ghcr.io/appaloft/appaloft` 提供，标签同时支持 `1.3.2` 与 `v1.3.2` 两种语义化命名，方便 CI/CD 与运维人员按各自约定使用。资料来源：[Dockerfile:1-30]()
## 自托管编排（Self-host Compose）
`docker-compose.selfhost.yml` 是社区推荐的自托管入口文件，将控制面、数据库、缓存等依赖统一编排：
```yaml
# 简化结构示意
services:
appaloft:
image: ghcr.io/appaloft/appaloft:1.3.2
restart: unless-stopped
depends_on: [db, redis]
db:
image: postgres:16
redis:
image: redis:7
```
通过 `docker compose -f docker-compose.selfhost.yml up -d` 即可拉起完整控制面，所有卷挂载均集中在同级目录，便于备份与迁移。资料来源：[docker-compose.selfhost.yml:1-60]()
## 边缘代理与证书自动化
控制面需要把应用流量安全地暴露到公网，因此 Appaloft 通过 Provider 接口把边缘代理与证书颁发解耦：
- **Caddy 边缘代理**：`edge-proxy-caddy` Provider 负责生成 Caddyfile 片段并通过本地管理 API 应用变更，支持 HTTP/3、TLS 终止与按域名路由。资料来源：[packages/providers/edge-proxy-caddy/src/index.ts:1-80]()
- **ACME 证书**：`certificate-acme` Provider 配合 Caddy 或独立 ACME 客户端完成 DNS-01 / HTTP-01 校验，并自动续期。资料来源：[packages/providers/certificate-acme/src/index.ts:1-80]()
调用顺序通常是：部署规划 → 申请证书 → 写入边缘代理 → 切换流量。
## SSH 部署目标与零配置规划
对于裸机或虚拟机目标，平台通过 `generic-ssh` Provider 把控制面生成的部署计划推送到远端主机。该 Provider 负责上传构建产物、远程执行 docker / systemd 命令并回采日志。资料来源：[packages/providers/generic-ssh/src/index.ts:1-80]()
v1.3.0 引入了更广泛的零配置部署规划能力，能在缺少完整描述时自动推断运行时、端口与健康检查 资料来源：[v1.3.0 release notes](https://github.com/appaloft/appaloft/releases/tag/v1.3.0)；同时沙箱子系统开始流式输出 Agent 运行事件，便于在 SSH 目标上观察长任务进度 资料来源：[v1.3.0 release notes](https://github.com/appaloft/appaloft/releases/tag/v1.3.0)。
## 基础设施数据流
```mermaid
flowchart LR
A[用户 / CI] -->|install.sh / docker pull| B[控制面]
B --> C[零配置规划]
C --> D{目标类型}
D -->|容器| E[ghcr.io/appaloft]
D -->|裸机/VM| F[generic-ssh]
B --> G[certificate-acme]
G --> H[edge-proxy-caddy]
H --> I[公网流量]
```
## 安全与运维注意事项
- v1.0.2 改进了密钥轮换与控制面 Secret 解密流程，当解密或轮换无法安全完成时选择**失败关闭**而非回退到旧密钥，避免出现解密与轮换不一致的窗口期。资料来源：[v1.0.2 release notes](https://github.com/appaloft/appaloft/releases/tag/v1.0.2)
- v1.0.3 修复了 release-please 的版本边界问题，确保 tag 与 changelog 严格对齐。资料来源：[v1.0.3 release notes](https://github.com/appaloft/appaloft/releases/tag/v1.0.3)
- 自托管部署建议把 `docker-compose.selfhost.yml` 中的数据卷纳入定期快照策略，控制面数据库与证书材料均为关键恢复点。
通过上述组件的组合，Appaloft 在保持单二进制 / 单镜像简洁形态的同时，提供了从安装、规划、暴露到证书续期的端到端自托管基础设施能力。
---
## 扩展性：插件、提供商与蓝图
### 相关页面
相关主题：[核心功能：部署、沙箱与代理工作区](#page-3), [部署、自托管与基础设施](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/plugins/sdk/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/plugins/sdk/src/index.ts)
- [packages/plugins/host/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/plugins/host/src/index.ts)
- [packages/providers/core/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/core/src/index.ts)
- [packages/blueprints/src/index.ts](https://github.com/appaloft/appaloft/blob/main/packages/blueprints/src/index.ts)
- [packages/application/src/extensibility/connector-registry.ts](https://github.com/appaloft/appaloft/blob/main/packages/application/src/extensibility/connector-registry.ts)
- [docs/PLUGINS.md](https://github.com/appaloft/appaloft/blob/main/docs/PLUGINS.md)
- [packages/application/src/extensibility/plugin-loader.ts](https://github.com/appaloft/appaloft/blob/main/packages/application/src/extensibility/plugin-loader.ts)
- [packages/providers/core/src/provider-registry.ts](https://github.com/appaloft/appaloft/blob/main/packages/providers/core/src/provider-registry.ts)
# 扩展性：插件、提供商与蓝图
Appaloft 的扩展能力由三层相互配合的子系统组成：**插件 SDK / Host** 负责生命周期与隔离、**Provider 注册表** 抽象后端能力、**Blueprint** 提供可复用的部署模板。它们在 `connector-registry` 中汇总，使应用层可以在不修改核心代码的前提下接入新的目标平台、新的资源类型以及新的部署策略。资料来源：[docs/PLUGINS.md:1-40]()。
## 三层扩展模型
Appaloft 将扩展点划分为三个正交的维度，彼此通过明确的契约解耦：
| 层级 | 关注点 | 代表模块 |
|------|--------|----------|
| Plugin（插件） | 行为注入、生命周期钩子 | `packages/plugins/sdk`、`packages/plugins/host` |
| Provider（提供商） | 后端抽象、外部服务对接 | `packages/providers/core` |
| Blueprint（蓝图） | 可复用拓扑与策略模板 | `packages/blueprints` |
插件位于运行时内部，向应用进程注入能力；提供商位于能力层，把 AWS、GCP、Kubernetes、Sandbox 等异构后端统一为同一组接口；蓝图位于声明层，把"要部署什么"和"通过谁去部署"分离开来。资料来源：[packages/providers/core/src/index.ts:12-58]()、[packages/blueprints/src/index.ts:8-44]()。
## 插件 SDK 与 Host
`@appaloft/plugin-sdk` 暴露插件作者需要的稳定 API：清单（manifest）、能力声明、上下文对象以及生命周期钩子（`onLoad`、`onPlan`、`onApply`、`onDestroy`）。插件在打包时声明其依赖的 provider 与 blueprint 名称，避免在运行时发生隐式依赖。资料来源：[packages/plugins/sdk/src/index.ts:24-96]()。
Host 端负责把插件载入沙箱：它校验清单签名、限制可访问的命名空间、为每个插件分配独立的 `PluginContext`，并通过 `Bridge` 把钩子调用转发给宿主进程。Host 还会捕获插件抛出的错误并向控制面回传状态，避免单个插件故障导致整个 `appaloft deploy` 中断。资料来源：[packages/plugins/host/src/index.ts:42-118]()。
`plugin-loader` 是 Host 与应用层之间的桥梁：它扫描 `APPALOFT_PLUGINS_PATH` 环境变量指定的目录，按优先级合并内置插件与外部插件，并在启动时输出解析后的清单供调试使用。资料来源：[packages/application/src/extensibility/plugin-loader.ts:30-88]()。
## Provider 与 Connector 注册表
`providers/core` 定义了所有后端必须实现的最小契约 `Provider`：`plan`、`apply`、`destroy`、`status`。注册表 `provider-registry` 按 `provider` 字符串（例如 `aws`、`kubernetes`、`sandbox`）索引实现，使得蓝图与插件无须关心具体厂商。资料来源：[packages/providers/core/src/provider-registry.ts:18-66]()。
为了在扩展点上保持一致，Appaloft 把"任何需要认证、调用远程 API 或管理凭据的对象"统称为 **Connector**。`connector-registry` 在应用启动时构造一个共享的连接器池，统一处理凭据读取、密钥解密失败时的 fail-closed 行为（参见 1.0.2 的安全修复），并把连接器按命名空间暴露给插件与蓝图。资料来源：[packages/application/src/extensibility/connector-registry.ts:24-102]()。
```mermaid
flowchart LR
Plugin[Plugin SDK] --> Host[Plugin Host]
Host --> Loader[plugin-loader]
Loader --> Core[Appaloft Core]
Core --> Reg[provider-registry]
Core --> Conn[connector-registry]
Blueprint[Blueprint] --> Reg
Reg --> AWS[(AWS)]
Reg --> K8s[(Kubernetes)]
Reg --> SB[(Sandbox)]
Conn --> Secrets[(Secrets/控制面)]
```
## Blueprint 的复用与组合
Blueprint 是声明式的部署模板，描述"组件拓扑 + 提供商选择 + 策略"。它通过 `blueprint.resolve(plan)` 在零配置场景下被自动挑选，也允许用户在 `appaloft deploy --blueprint ` 中显式指定。1.3.0 引入的 "broaden zero-config planning" 正是基于 Blueprint 选择器的扩展，使其能覆盖更多运行时形态。资料来源：[packages/blueprints/src/index.ts:46-120]()、[https://github.com/appaloft/appaloft/releases/tag/v1.3.0]()。
Blueprint 之间支持 `extends` 与 `mixins`，使得一个 Web 服务蓝图可以继承 `base.runtime` 并混入 `observability` 而不必重复定义。解析器会输出合并后的拓扑与冲突点，供 `appaloft plan` 渲染差异。资料来源：[packages/blueprints/src/index.ts:128-176]()。
## 选型建议与互操作
1. **编写行为扩展**（如新增部署策略、命令）应选择插件形态：使用 SDK 暴露稳定的钩子，并在 Host 沙箱内运行。资料来源：[packages/plugins/sdk/src/index.ts:24-96]()。
2. **接入新后端**（新的云厂商或自建 K8s）应实现 `Provider` 接口并在 `provider-registry` 中注册，再让 Blueprint 通过引用切换。资料来源：[packages/providers/core/src/provider-registry.ts:18-66]()。
3. **构造可复用拓扑**时优先使用 Blueprint，避免在插件中硬编码资源关系。
4. **凭据与连接**统一通过 `connector-registry`，便于集中审计并复用 1.0.2 引入的密钥 fail-closed 保护。资料来源：[https://github.com/appaloft/appaloft/releases/tag/v1.0.2]()。
这套分层让 Appaloft 能在不修改核心的前提下同时支持云端、集群与 Sandbox（参见 1.3.0 引入的 `stream agent run events`）等多种目标。资料来源：[https://github.com/appaloft/appaloft/releases/tag/v1.3.0]()。
---
---
## Doramagic 踩坑日志
项目：appaloft/appaloft
摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。
## 1. 能力坑 · 能力证据存在缺口
- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/appaloft/appaloft | Sandbox install result is missing.
## 2. 安装坑 · 安装命令尚未沙箱验证
- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`bun run build`
- 证据：downstream_validation.install_status | https://github.com/appaloft/appaloft | install_status=documented; command=bun run build
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/appaloft/appaloft | README/documentation is current enough for a first validation pass.
## 4. 运行坑 · Quick Start 尚未实际跑通
- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/appaloft/appaloft | quickstart_status=not_attempted; sandbox_quickstart_status=missing
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/appaloft/appaloft | no_demo; severity=medium
## 7. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/appaloft/appaloft | No sandbox install has been executed yet; downstream must verify before user use.
## 8. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/appaloft/appaloft | no_demo; severity=medium
## 9. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | issue_or_pr_quality=unknown
## 10. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | release_recency=unknown