# https://github.com/las7/TakoVM 项目说明书

生成时间：2026-06-07 04:20:38 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [核心功能与使用模式](#page-2)
- [安全模型与生产运维](#page-3)
- [API、SDK 与配置参考](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[核心功能与使用模式](#page-2), [安全模型与生产运维](#page-3), [API、SDK 与配置参考](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/las7/TakoVM/blob/main/README.md)
- [mkdocs.yml](https://github.com/las7/TakoVM/blob/main/mkdocs.yml)
- [tako_vm/__init__.py](https://github.com/las7/TakoVM/blob/main/tako_vm/__init__.py)
- [tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py)
- [tako_vm/config.py](https://github.com/las7/TakoVM/blob/main/tako_vm/config.py)
- [tako_vm/models.py](https://github.com/las7/TakoVM/blob/main/tako_vm/models.py)
- [tako_vm/job_types.py](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.py)
- [tako_vm/job_types.json](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.json)
- [tako_vm/storage.py](https://github.com/las7/TakoVM/blob/main/tako_vm/storage.py)
- [tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)
- [tako_vm/security.py](https://github.com/las7/TakoVM/blob/main/tako_vm/security.py)
- [tako_vm/execution/builder.py](https://github.com/las7/TakoVM/blob/main/tako_vm/execution/builder.py)
- [tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)
</details>

# 项目概述与系统架构

Tako VM 是一个面向 Python AI Agent 的**任务队列基础设施**（Job Queue Infrastructure）。它通过预构建的 Docker 容器为不可信或资源密集的 Python 代码提供**可审计、可复现**的沙箱执行环境。系统的核心设计目标是：把"提交一段 Python 函数"变成一个具备幂等性、版本化、审计可追溯的远程任务。

## 项目定位与目标场景

Tako VM 解决的是"AI Agent 产出的代码片段如何在生产环境中安全执行"的问题。它的运行模式与传统的 Celery/RQ 等任务队列在概念上类似，但侧重点不同：

- **容器化执行**：每个任务在独立的 Docker 容器中运行，依赖通过 job type 预装 资料来源：[tako_vm/job_types.py:1-15]()
- **审计级记录**：每次执行生成 `ExecutionRecord`，包含代码哈希、输入哈希、参数哈希、退出码、资源使用、错误 JSON 等字段 资料来源：[tako_vm/models.py:1-50]()
- **幂等性支持**：通过 `idempotency_key` 唯一索引保证重复提交返回相同结果 资料来源：[tako_vm/storage.py:25-40]()
- **版本化任务类型**：基于内容哈希（SHA256）计算 digest，支持 `@v1.0.0` 形式的语义版本别名 资料来源：[tako_vm/version.py:30-50]()

项目通过 `mkdocs.yml` 组织文档，分为 Getting Started、Architecture、API Reference、Guide 等板块 资料来源：[mkdocs.yml:25-50]()，说明它面向**自部署的工程团队**而非托管服务用户。

## 系统架构

Tako VM 采用经典的**服务端 + 异步 Worker** 架构，对外暴露 REST API 和 Python SDK 两种入口。系统组件及数据流如下：

```mermaid
flowchart LR
    Client[客户端 / SDK] -->|HTTP / send| API[FastAPI 服务端<br/>tako_vm/server/app.py]
    API -->|写入| DB[(PostgreSQL<br/>execution_records)]
    API -->|入队| Queue[任务队列]
    Queue -->|取任务| Worker[Worker Pool]
    Worker -->|docker run| Container[隔离容器]
    Container -->|结果写回| DB
    Container -->|stdout/stderr| Security[安全模块<br/>sanitize + cap]
    Security -->|记录| API
    API -->|查询/回调| Client
```

关键模块职责：

| 模块 | 文件 | 职责 |
|------|------|------|
| HTTP 服务 | `tako_vm/server/app.py` | 暴露 REST 端点、参数校验、分页、视图切换（`?view=full`）|
| CLI 入口 | `tako_vm/cli.py` | 提供 `server / dev / status / validate / config / setup / version` 子命令 |
| 配置管理 | `tako_vm/config.py` | Pydantic 模型 + YAML 加载，含严格边界校验 |
| 任务类型 | `tako_vm/job_types.py` | 定义 `JobType` 数据类与 `JobTypeRegistry` 注册表 |
| 持久层 | `tako_vm/storage.py` | PostgreSQL 连接池、`execution_records` / `job_versions` 表 |
| 版本管理 | `tako_vm/version.py` | 基于内容哈希的 digest 计算、版本标签解析 |
| 镜像构建 | `tako_vm/execution/builder.py` | 为 job type 生成 Dockerfile 并执行 `docker build` |
| 安全 | `tako_vm/security.py` | 输出截断、错误脱敏、镜像名/环境变量校验 |

服务端提供分页接口（`limit` 上限 1000）与 `?view=full` 扩展视图，包含 artifacts、lineage 等信息 资料来源：[tako_vm/server/app.py:1-40]()。

## 核心执行模型

Tako VM 的执行流程与社区中常被误解的"本地函数"模式有本质区别，这一点在 issue #39 中被特别指出。Python SDK 的 `@tako.send()` 装饰器**不会在本地执行函数体**，而是：

1. **序列化**函数源码与参数（按类型提示做序列化）
2. **入队**到 `execution_records` 表，分配 `idempotency_key`
3. **拉取**：Worker Pool 从队列中取出 pending 任务
4. **运行**：在匹配的 job type 容器中执行，捕获 `stdout`/`stderr`/`exit_code`
5. **归档**：资源使用、错误结构化字段、artifacts 全部入库

需要特别注意的是 `pending` 与 `queued` 在 API 文档中存在混用（issue #29）。从源码看，`status` 字段是记录级状态，队列状态由后台调度状态决定，二者需在文档中明确区分 资料来源：[tako_vm/models.py:30-60]()、`tako_vm/storage.py:20-40]()。

预置的 `default`、`data-processing`、`ml-inference`、`test-with-secrets` 等 job type 来自 `tako_vm/job_types.json`，其中 `test-with-secrets` 显式演示了环境变量注入模式 资料来源：[tako_vm/job_types.json:1-80]()。

## 安全模型与已知风险

Tako VM 在 `tako_vm/security.py` 中实现了多层防护：64KB 的 stdout/stderr 截断、敏感路径与容器 ID 的正则脱敏、环境变量键值校验、pip 需求白名单等 资料来源：[tako_vm/security.py:1-30]()。同时 `validate_docker_image`、`validate_env_key` 等函数在容器构建阶段阻止危险输入 资料来源：[tako_vm/execution/builder.py:20-35]()。

然而，**安全是当前文档与实现的薄弱环节**，与社区关切高度相关：

- **CRITICAL 风险**：环境变量可通过容器内 `/proc/self/environ` 被运行时代码读取（issue #40）。`test-with-secrets` job type 仍以明文存储 `API_KEY`，说明当前未做加密或 secret mount 隔离。
- **缓解文档未落地**：`docs/security/mitigations.md` 列出了 Phase 1–4 路线图，但多数条目尚未实现（issue #32）。开发者不应把它当作"已修复"的功能。
- **CLI 文档错位**：旧文档引用了不存在的 `tako-vm build job-type <name>` 与 `python -m tako_vm.container_builder --build-all` 命令（issue #30、#37）。实际构建入口是 `tako-vm setup` 或经由 `ContainerBuilder` 类 资料来源：[tako_vm/cli.py:1-50]()`tako_vm/execution/builder.py:1-30]()`。

> 实践建议：在将 Tako VM 投入生产前，**始终假设环境变量在容器内可被任意读取**，把敏感凭据放到 Vault 等外部系统并通过短期 token 注入。

## See Also

- 入门：安装、Quick Start、配置
- API：REST API、Python SDK
- 指南：Job Type 与环境、自定义库
- 部署：生产部署、扩缩容、运维 Runbook（待补）

---

<a id='page-2'></a>

## 核心功能与使用模式

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [安全模型与生产运维](#page-3), [API、SDK 与配置参考](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tako_vm/models.py](https://github.com/las7/TakoVM/blob/main/tako_vm/models.py)
- [tako_vm/job_types.py](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.py)
- [tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)
- [tako_vm/storage.py](https://github.com/las7/TakoVM/blob/main/tako_vm/storage.py)
- [tako_vm/security.py](https://github.com/las7/TakoVM/blob/main/tako_vm/security.py)
- [tako_vm/config.py](https://github.com/las7/TakoVM/blob/main/tako_vm/config.py)
- [tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py)
- [tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)
- [tako_vm/execution/builder.py](https://github.com/las7/TakoVM/blob/main/tako_vm/execution/builder.py)
- [tako_vm/job_types.json](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.json)
- [tako_vm/__init__.py](https://github.com/las7/TakoVM/blob/main/tako_vm/__init__.py)
- [README.md](https://github.com/las7/TakoVM/blob/main/README.md)
- [mkdocs.yml](https://github.com/las7/TakoVM/blob/main/mkdocs.yml)
</details>

# 核心功能与使用模式

## 概述与核心组件

Tako VM 是一个面向 Python AI 代理的任务队列基础设施，其核心思路是把"运行环境预定义 + 代码序列化提交 + 容器化隔离执行"组合成一套可审计的批处理系统。包级别的公开 API 由 [tako_vm/__init__.py](https://github.com/las7/TakoVM/blob/main/tako_vm/__init__.py) 统一导出，涵盖 `JobTypeRegistry`、`ExecutionRecord`、`ResourceUsage`、`Artifact`、`JobVersion` 等模型与异常类型。

系统的关键抽象包括：

- **JobType**：预定义容器模板，决定依赖、Python 版本、资源限制、是否启用 GPU、是否启用 session 等（资料来源：[tako_vm/job_types.py](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.py)）。
- **ExecutionRecord**：审计级别的执行记录，持久化到 PostgreSQL，包含 `code_hash`、`input_hash`、`params_hash`、`exit_code`、`resource usage` 等字段（资料来源：[tako_vm/models.py](https://github.com/las7/TakoVM/blob/main/tako_vm/models.py)）。
- **VersionManager**：基于内容哈希为 JobType 计算 `digest`，支持按 `sha256:...` 摘要或语义化 tag 查询版本（资料来源：[tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)）。
- **REST API + Python SDK**：通过 `tako-vm server` 启动 FastAPI 服务，对外暴露 `/executions/{id}` 等接口（资料来源：[tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)）。

## 任务提交与执行模型

社区多次反馈 SDK 的 `send()` 执行模型说明不足（参见 [Issue #39](https://github.com/las7/TakoVM/issues/39)）。需要特别强调：**装饰器修饰的函数体不会在本地执行**，而是被序列化（基于类型提示做参数/返回值的编解码）后投递到服务端，再由 worker 在 Docker 容器中运行。因此类型提示在这里承担双重职责：既是静态检查，也驱动了跨进程的数据序列化。

执行生命周期在存储层有明确体现。`execution_records` 表通过 `status` 索引加速轮询，并通过 `(status, job_type, created_at DESC)` 复合索引支撑高效分页（资料来源：[tako_vm/storage.py](https://github.com/las7/TakoVM/blob/main/tako_vm/storage.py)）。客户端可通过 `GET /executions/{id}` 查询单条记录，或通过分页接口 `GET /executions?view=full` 拉取包含 `artifacts`、`resource_usage`、`code_hash` 等的完整响应（资料来源：[tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)）。

需要区分两个看似相近的状态：

| 维度 | 含义 |
|------|------|
| 队列层状态 | 任务在队列中的位置（如 `pending`） |
| 记录层状态 | 持久化记录中的执行阶段（如 `queued`） |

由于历史文档将两套状态混用（参见 [Issue #29](https://github.com/las7/TakoVM/issues/29)），轮询时建议同时关注 `status` 与 `created_at` 的组合，避免因状态命名混淆而误判任务进度。

## JobType 定义、构建与版本化

每个 JobType 是一段 JSON/YAML 配置，描述如何构造 Docker 镜像。`tako_vm/job_types.json` 中提供了 `default`、`data-processing`、`ml-inference` 等示例，其中 `data-processing` 预装 `pandas`、`numpy` 并设置 `memory_limit=1g`、`cpu_limit=2.0`（资料来源：[tako_vm/job_types.json](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.json)）。

构建流程由 [tako_vm/execution/builder.py](https://github.com/las7/TakoVM/blob/main/tako_vm/execution/builder.py) 中的 `ContainerBuilder` 承担：`generate_dockerfile()` 会校验 `python_version`、`requirements`、`environment` 等字段，调用 `validate_pip_requirement`、`validate_env_key`、`validate_env_value` 等安全工具后再生成 Dockerfile。版本摘要由 `VersionManager.compute_digest()` 计算，纳入哈希的字段包含 `requirements`、`python_version`、`base_image`、`environment`、`shared_code`、`session_enabled`、GPU 配置等（资料来源：[tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)），这保证只要"影响镜像内容"的字段变化，就会得到新的 `sha256:...` 摘要。

下面用一个架构图概括从配置到执行的端到端流程：

```mermaid
flowchart LR
    A[JobType 配置] --> B[VersionManager.compute_digest]
    B --> C[sha256 摘要]
    A --> D[ContainerBuilder.generate_dockerfile]
    D --> E[Docker 镜像 image_ref]
    C --> F[execution_records]
    E --> F
    G[SDK send / REST POST] --> F
    F --> H[Worker 拉起容器]
    H --> I[stdout / stderr / artifacts]
    I --> J[ResourceUsage + ErrorType]
```

## 配置、安全与常见误区

服务端配置通过 YAML 加载，搜索路径依次为 `./tako_vm.yaml`、`config/tako_vm.yaml`、`~/.tako_vm/config.yaml`、`/etc/tako_vm/config.yaml`（资料来源：[tako_vm/config.py](https://github.com/las7/TakoVM/blob/main/tako_vm/config.py)）。CLI 支持 `server`、`dev up/down/status`、`status`、`validate`、`config`、`setup`、`version` 等子命令（资料来源：[tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py)）。

**关于安全与文档偏差的几点提醒**：

1. **环境变量暴露**：`docs/security/mitigations.md` 把通过 `/proc/self/environ` 读取 env 标记为 `Priority: CRITICAL`（参见 [Issue #40](https://github.com/las7/TakoVM/issues/40)）。即便 `JobType.environment` 只是传给容器的环境变量，也应避免写入 API key、数据库密码等敏感值；优先使用服务端 secret store。
2. **不存在的 CLI 命令**：`tako-vm build job-type <name>` 在多处文档中被引用，但 [tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py) 中并无 `build` 子命令（参见 [Issue #30](https://github.com/las7/TakoVM/issues/30)）。当前构建路径应通过 `ContainerBuilder` 的 Python API 或 `tako-vm setup` 触发。
3. **不存在的 `python -m` 命令**：`python -m tako_vm.execution.builder --init-defaults all` 与 `python -m tako_vm.container_builder --build-all` 均无对应实现（参见 [Issue #37](https://github.com/las7/TakoVM/issues/37)），请勿照搬旧文档。
4. **先决条件缺失**：Docker 镜像构建并非"可选"，提交任务前必须先有可用的 `image_ref`；同时 PostgreSQL 需在 `quickstart` 之前就位（参见 [Issue #31](https://github.com/las7/TakoVM/issues/31)）。

安全模块本身已经做了不少兜底：`security.py` 中的 `SANITIZE_PATTERNS` 会把临时目录、用户家目录、容器 ID、IP 等敏感信息从错误消息中替换为占位符（资料来源：[tako_vm/security.py](https://github.com/las7/TakoVM/blob/main/tako_vm/security.py)）。结合上述限制与模型层的 `ErrorType` 字面量（涵盖 `oom`、`segfault`、`execution_timeout` 等分类），可以在排查失败原因时既保留足够信号，又避免泄漏宿主与容器拓扑信息。

## 参见

- [架构总览](architecture.md)
- [安装与先决条件](getting-started/installation.md)
- [快速开始](getting-started/quickstart.md)
- [配置参考](getting-started/configuration.md)
- [REST API](api/rest.md)
- [Python SDK](api/sdk.md)
- [运行环境与 JobType 指南](guide/environments.md)

---

<a id='page-3'></a>

## 安全模型与生产运维

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [核心功能与使用模式](#page-2), [API、SDK 与配置参考](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tako_vm/security.py](https://github.com/las7/TakoVM/blob/main/tako_vm/security.py)
- [tako_vm/models.py](https://github.com/las7/TakoVM/blob/main/tako_vm/models.py)
- [tako_vm/config.py](https://github.com/las7/TakoVM/blob/main/tako_vm/config.py)
- [tako_vm/job_types.py](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.py)
- [tako_vm/job_types.json](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.json)
- [tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)
- [tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py)
- [tako_vm/execution/builder.py](https://github.com/las7/TakoVM/blob/main/tako_vm/execution/builder.py)
- [tako_vm/storage.py](https://github.com/las7/TakoVM/blob/main/tako_vm/storage.py)
- [tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)
</details>

# 安全模型与生产运维

## 概述

Tako VM 是一个面向 Python AI 代理的作业队列基础设施，其安全模型围绕「容器化隔离 + 入口/出口内容净化 + 资源配额」三层展开。生产运维层面，系统通过 CLI 与 REST API 提供配置校验、构建、状态查询、版本注册等能力，但部分文档与 CLI 仍存在不一致（详见 [Issue #30](https://github.com/las7/TakoVM/issues/30) 与 [Issue #37](https://github.com/las7/TakoVM/issues/37)），运维人员需要按本文档核对当前实际可用的命令集合。

## 一、安全模型核心

### 1.1 错误信息与输出净化

`tako_vm/security.py` 定义了 `SANITIZE_PATTERNS` 列表，对错误信息中的敏感路径与标识符进行脱敏处理：

- 临时目录：`/tmp/job-***`、`/var/folders/***`
- 用户主目录：`/Users/...`、`/home/...`
- 容器内部路径：`/app/***`
- 内网 IP：`172.x.x.x`、`10.x.x.x`、`192.168.x.x`
- Docker 容器 ID：64 位或 12 位十六进制串统一替换为 `<container-id>`

同时 `DEFAULT_MAX_STDOUT_BYTES` 与 `DEFAULT_MAX_STDERR_BYTES` 默认为 64 KB，对执行产物的 stdout/stderr 实施大小上限，避免容器把任意大小输出写回主机。

`tako_vm/models.py` 进一步规范了 `ErrorType` 枚举，覆盖 `oom`、`cancelled`、`segfault`、`abort`、`arithmetic_error`、`bus_error`、`pipe_error` 等信号级错误，以及 `startup_timeout` / `execution_timeout` 两个阶段级超时。这些值在记录 `execution_records` 时作为规范化字段使用，便于死信队列的统计与告警（[REST 端点 `/dlq/stats`](tako_vm/server/app.py) 即依赖该规范化）。

### 1.2 已知安全风险

社区文档指出，**通过 `/proc/self/environ` 读取环境变量** 被标记为 Priority: CRITICAL（[Issue #40](https://github.com/las7/TakoVM/issues/40)）。在 `tako_vm/job_types.json` 的 `test-with-secrets` 示例中，容器以环境变量形式注入了 `API_KEY` 与 `DATABASE_URL`，这正是上述风险的演示场景。运维人员应在 `JobType.environment` 中**避免**写入长期凭据，改用外部 secret 注入或短时效 token。

### 1.3 输入校验

`ContainerBuilder.generate_dockerfile` 在生成 Dockerfile 之前调用 `validate_python_version`、`validate_env_key`、`validate_env_value`、`validate_pip_requirement`、`validate_docker_image` 等函数进行预校验，校验失败抛出 `BuildError`。这保证镜像构建阶段即拒绝恶意或畸形配置。

## 二、容器执行沙箱

`JobType` 数据类（[tako_vm/job_types.py](tako_vm/job_types.py)）是沙箱配置的来源，关键字段如下：

| 字段 | 含义 | 默认值 |
|------|------|--------|
| `memory_limit` | 容器内存上限 | `512m` |
| `cpu_limit` | CPU 配额 | `1.0` |
| `timeout` | 代码执行超时（秒） | `30` |
| `startup_timeout` | 依赖安装阶段超时 | `120` |
| `network_enabled` | 是否启用网络 | `False` |
| `gpu_enabled` | 是否挂载 GPU | `False` |

`tako_vm/config.py` 中的 `ContainerLimits` 进一步约束文件描述符（`nofile_soft/hard`）与进程数（`nproc_soft`），使用 Pydantic 字段约束 `ge=64, le=65536` 等上下界，防止运维误配导致容器逃逸或主机耗尽资源。

`network_enabled` 默认 `False` 意味着容器在大多数场景下无法出网，这是阻断数据外泄与依赖混淆攻击的关键防线。`session_enabled` 用于启用跨多次调用的会话容器，开启后需要更严格的清理策略。

## 三、生产运维

### 3.1 可用的 CLI 子命令

`tako_vm/cli.py` 中实际存在的子命令为：`server`、`dev (up/down/status)`、`status`、`validate`、`config [--json] [--show-defaults]`、`setup`、`version`。`setup` 拉取执行器镜像并验证 Docker 可用性。**没有** `tako-vm build job-type` 子命令，构建动作必须通过 REST API `/job-types/{name}/build` 触发（[tako_vm/server/app.py](tako_vm/server/app.py)），该端点会调用 `ContainerBuilder.build()` 并通过 `VersionManager.register_version()` 写入 `job_versions` 表。

### 3.2 版本与幂等

`VersionManager.compute_digest()`（[tako_vm/version.py](tako_vm/version.py)）基于 requirements、python 版本、基础镜像、环境变量、会话/GPU 配置等序列化后取 SHA256，保证「相同配置 + 相同依赖 ⇒ 相同 digest ⇒ 可复现构建」。`storage.py` 在 `execution_records` 上对 `idempotency_key` 建立 `UNIQUE` 部分索引，配合调用方传入的幂等键实现「重复请求同结果」，这是生产环境避免重复扣费或重复副作用的核心机制。

### 3.3 运行状态查询

- `GET /pool/stats` —— 当前 worker 池统计
- `GET /dlq/stats` —— 死信队列聚合
- `GET /dlq?error_type=...` —— 分页列出死信记录
- `GET /executions?view=full` —— 审计级记录（含 artifacts、资源用量、内容哈希与父子链路）

### 3.4 待补齐的运维 Runbook

社区已记录到 `docs/deployment/scaling.md` 将容器池、分布式 worker、S3 存储等列为「Planned」但未区分现状（[Issue #34](https://github.com/las7/TakoVM/issues/34)），同时缺乏熔断器跳闸、DLQ 积压、Docker 守护进程崩溃等场景的 runbook（[Issue #33](https://github.com/las7/TakoVM/issues/33)）。生产部署前，运维团队应自行编写：①熔断跳闸后的隔离与恢复步骤；②DLQ 复放/清空流程；③Docker 守护进程崩溃的健康检查与告警阈值。

## 四、API 中作业状态字段

REST 文档中存在 `pending`（队列状态）与 `queued`（记录状态）混用的问题（[Issue #29](https://github.com/las7/TakoVM/issues/29)）。轮询 `/executions/{id}` 的客户端应同时识别两值，并结合 `created_at` 排序判断作业是否已离开调度层。

## See Also

- [配置参考](./getting-started/configuration.md)
- [REST API 参考](./api/rest.md)
- [Job Types 与执行环境](./guide/environments.md)
- [部署指南](./deployment/how-to-deploy.md)

---

<a id='page-4'></a>

## API、SDK 与配置参考

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [核心功能与使用模式](#page-2), [安全模型与生产运维](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tako_vm/sdk/client.py](https://github.com/las7/TakoVM/blob/main/tako_vm/sdk/client.py)
- [tako_vm/sdk/__init__.py](https://github.com/las7/TakoVM/blob/main/tako_vm/sdk/__init__.py)
- [tako_vm/server/app.py](https://github.com/las7/TakoVM/blob/main/tako_vm/server/app.py)
- [tako_vm/models.py](https://github.com/las7/TakoVM/blob/main/tako_vm/models.py)
- [tako_vm/config.py](https://github.com/las7/TakoVM/blob/main/tako_vm/config.py)
- [tako_vm/cli.py](https://github.com/las7/TakoVM/blob/main/tako_vm/cli.py)
- [tako_vm/version.py](https://github.com/las7/TakoVM/blob/main/tako_vm/version.py)
- [tako_vm/security.py](https://github.com/las7/TakoVM/blob/main/tako_vm/security.py)
- [tako_vm/job_types.py](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.py)
- [tako_vm/job_types.json](https://github.com/las7/TakoVM/blob/main/tako_vm/job_types.json)
- [tako_vm/storage.py](https://github.com/las7/TakoVM/blob/main/tako_vm/storage.py)
- [tako_vm/__init__.py](https://github.com/las7/TakoVM/blob/main/tako_vm/__init__.py)
- [mkdocs.yml](https://github.com/las7/TakoVM/blob/main/mkdocs.yml)
- [README.md](https://github.com/las7/TakoVM/blob/main/README.md)
</details>

# API、SDK 与配置参考

Tako VM 的对外接口由三层组成：**Python SDK** 提供类型化函数装饰器以提交执行任务，**REST API** 暴露执行记录的查询、过滤与异步任务管理能力，**YAML 配置文件**与**CLI 子命令**定义 Job Type、容器资源限制与基础设施选项。本页基于仓库源码逐层说明可用的入口、参数与数据形状，并标注社区文档中常见的误解点。

## 1. Python SDK 客户端

`tako_vm/sdk/__init__.py` 是 SDK 的公共入口，导出 `send`、`send_raw`、`configure`、`list_job_types`、`get_job_type`、`TakoVM`、`ExecutionResult`、`TakoVMError`、`ExecutionError` 与 `ValidationError` 资料来源：[tako_vm/sdk/__init__.py:1-31]()。

`send` 是装饰器，其核心语义需要特别强调：**被装饰的函数体不会在本地运行**——它会被序列化为源码与类型提示，投递到 Tako VM 服务器，由指定 Job Type 的容器远程执行（社区 issue #39 指出此执行模型常被误解）。`send_raw` 则允许以原始载荷提交代码片段，绕过装饰器的类型推断。`configure` 用于设置服务端点与 API Key 等全局参数；`list_job_types` 与 `get_job_type` 用于查询已注册的 Job Type 清单 资料来源：[tako_vm/sdk/__init__.py:1-31]()。

```mermaid
sequenceDiagram
    participant U as 用户代码
    participant SDK as Tako VM SDK
    participant API as REST API
    participant DB as PostgreSQL
    U->>SDK: 装饰 send(fn)
    SDK->>SDK: 序列化 fn 源码 + 类型提示
    SDK->>API: POST /executions
    API->>DB: 插入 execution_record (status=queued)
    API-->>SDK: 返回 execution_id
    SDK-->>U: 立即返回
    Note over U,DB: 容器异步执行
    U->>API: GET /executions/{id}
    API->>DB: 查询
    DB-->>API: record
    API-->>U: ExecutionRecord (status=running|completed|failed)
```

SDK 抛出的异常层次为 `TakoVMError` → `SDKExecutionError`（向后兼容别名 `ExecutionError`）→ `ValidationError` 资料来源：[tako_vm/__init__.py:1-44]()。

## 2. REST API 端点

HTTP 服务由 `tako_vm/server/app.py` 提供。核心端点包括：

- `POST /executions` — 提交一次代码执行
- `GET /executions` — 列出执行记录，支持 `status`、`job_type`、`limit`、`offset` 过滤
- `GET /executions/{execution_id}` — 获取单条记录，附加 `?view=full` 可返回包含 artifacts、content hashes 与 lineage 的完整载荷

`limit` 参数最大为 1000，超出时服务端按 `min(limit, 1000)` 截断并通过 `has_more` 标志返回下一页是否存在 资料来源：[tako_vm/server/app.py:1-200]()。针对社区 issue #29 提出的 `pending` 与 `queued` 状态混淆：`queued` 是数据库记录层（已落库、等待调度）状态，`pending` 是队列层（worker 尚未拉取）状态；二者可在轮询生命周期中先后出现，开发者应根据业务语义选择合适的轮询点。

## 3. 配置与 CLI 实际可用命令

`tako_vm/config.py` 使用 Pydantic 进行严格边界校验，子模型通过 `model_config = {"extra": "forbid"}` 拒绝未声明字段 资料来源：[tako_vm/config.py:1-60]()。配置文件按以下顺序搜索：`./tako_vm.yaml` → `./config/tako_vm.yaml` → `~/.tako_vm/config.yaml` → `/etc/tako_vm/config.yaml` 资料来源：[tako_vm/config.py:1-30]()。

`JobType`（`tako_vm/job_types.py`）描述一个容器化执行环境：`requirements`、`python_version`、`base_image`、`shared_code`、`environment`、`memory_limit`、`cpu_limit`、`timeout`、`startup_timeout`、`network_enabled`、`session_enabled` 与 `gpu` 子字典 资料来源：[tako_vm/job_types.py:1-80]()。仓库提供的示例 `tako_vm/job_types.json` 内置了 `default`、`data-processing`、`ml-inference` 以及一个**故意暴露明文密钥**的 `test-with-secrets`——后者仅作为风险演示，不应在生产中启用（社区 issue #40 已警示环境变量可能通过 `/proc/self/environ` 泄露）资料来源：[tako_vm/job_types.json:1-200]()。

CLI 实际可用的子命令（`tako_vm/cli.py`）为：`server`、`dev {up,down,status}`、`status`、`validate [path]`、`config [--json] [--show-defaults]`、`setup`、`version` 资料来源：[tako_vm/cli.py:1-100]()。**注意**：文档中曾引用的 `tako-vm build job-type <name>`（社区 issue #30）以及 `python -m tako_vm.execution.builder`（社区 issue #37）目前不存在，请改用 `tako-vm setup` 拉取执行镜像后由服务端按需构建 Job Type。

## 4. 数据模型、版本与安全约束

执行记录由 `ExecutionRecord`（`tako_vm/models.py`）承载；`ResourceUsage` 约束 `max_rss_mb` ≤ 1TB、`cpu_time_ms` 与 `wall_time_ms` ≤ 24 小时 资料来源：[tako_vm/models.py:1-100]()。`Artifact` 的 `name` 字段禁止包含路径分隔符以防止目录穿越，`storage_key` 长度上限 1024 资料来源：[tako_vm/models.py:100-200]()。

`JobVersion` 通过 SHA256 内容哈希保证可复现构建，`full_ref` 形如 `name@sha256:<前 12 位摘要>`，对应镜像以 `tako-vm-<job_type>@sha256:...` 引用 资料来源：[tako_vm/models.py:200-280]()、`[tako_vm/version.py:1-80]()`。

错误分类由 `ErrorType` 字面量定义，区分 `startup_timeout`/`execution_timeout` 与信号类（`oom`、`cancelled`、`segfault`、`abort`、`arithmetic_error`、`bus_error`、`pipe_error`） 资料来源：[tako_vm/models.py:280-320]()。`tako_vm/security.py` 的 `SANITIZE_PATTERNS` 会在错误消息中替换临时目录、家目录、内网 IP 与容器 ID，避免敏感路径泄露到响应里 资料来源：[tako_vm/security.py:1-40]()。PostgreSQL 表 `execution_records` 还会为 `idempotency_key` 建立唯一索引，使重复提交得到去重 资料来源：[tako_vm/storage.py:1-80]()。

## See Also

- [架构总览](architecture.md)
- [REST API](api/rest.md)
- [Python SDK](api/sdk.md)
- [配置参考](getting-started/configuration.md)
- [安全缓解措施](security/mitigations.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：las7/takovm

摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Docs: add end-to-end example application。

## 1. 安装坑 · 来源证据：Docs: add end-to-end example application

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: add end-to-end example application
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_78a96aee28384d93b96002b77e6027ea | https://github.com/las7/TakoVM/issues/38 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Docs: add operational runbooks for production deployment

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: add operational runbooks for production deployment
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1702731d27b44ab483e81e1e39003db1 | https://github.com/las7/TakoVM/issues/33 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：Docs: getting-started missing prerequisites checklist

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: getting-started missing prerequisites checklist
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_31b37ccb63c64ad89eb926be535f46d5 | https://github.com/las7/TakoVM/issues/31 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Docs: non-existent python -m CLI commands in production.md and environments.md

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: non-existent python -m CLI commands in production.md and environments.md
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f10bb15a58f541479f103040c56f2845 | https://github.com/las7/TakoVM/issues/37 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：Docs: tako-vm build command referenced but doesn't exist in CLI

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: tako-vm build command referenced but doesn't exist in CLI
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a81c31adb886463ba3fe59c976ca6534 | https://github.com/las7/TakoVM/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 6. 能力坑 · 来源证据：Docs: scaling.md lists planned features without clarifying current state

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Docs: scaling.md lists planned features without clarifying current state
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_81231681c1d64897a42c17e87568c065 | https://github.com/las7/TakoVM/issues/34 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | README/documentation is current enough for a first validation pass.

## 8. 运行坑 · 来源证据：Docs: SDK send() execution model poorly explained

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Docs: SDK send() execution model poorly explained
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_14c9181db25446ecaa58b6cfef944ab4 | https://github.com/las7/TakoVM/issues/39 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 运行坑 · 来源证据：Docs: clarify pending vs queued job status

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Docs: clarify pending vs queued job status
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_726651d2543a41fcb2b12eacce59f8eb | https://github.com/las7/TakoVM/issues/29 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | last_activity_observed missing

## 11. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | no_demo; severity=medium

## 13. 安全/权限坑 · 来源证据：Add optional egress proxy for dependency installs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add optional egress proxy for dependency installs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8dcc73f80c184253a4646f4293c8e38c | https://github.com/las7/TakoVM/issues/15 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安全/权限坑 · 来源证据：Disable runtime dependency installs by default

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Disable runtime dependency installs by default
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_17ba6c128eaa4f4996dcd06c7d309f2b | https://github.com/las7/TakoVM/issues/14 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 安全/权限坑 · 来源证据：Docs: mitigations.md reads as issue tracker, not documentation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docs: mitigations.md reads as issue tracker, not documentation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_169ec35f009e4f86a8b322531f643e96 | https://github.com/las7/TakoVM/issues/32 | 来源类型 github_issue 暴露的待验证使用条件。

## 16. 安全/权限坑 · 来源证据：Docs: quickstart missing security warnings for env vars and /proc exposure

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docs: quickstart missing security warnings for env vars and /proc exposure
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e70e50033ee2425c80d460b507c69efd | https://github.com/las7/TakoVM/issues/40 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 17. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | issue_or_pr_quality=unknown

## 18. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | hn_item:48431257 | https://news.ycombinator.com/item?id=48431257 | release_recency=unknown

<!-- canonical_name: las7/takovm; human_manual_source: deepwiki_human_wiki -->