2.1 先否定一个直觉方案#

最直观的做法：开启 Canal 订阅增量 Binlog，同时用 Canal RDB Adapter 内置的 ETL 功能全量拉取主表存量数据，最后改应用配置完成切表。

看似闭环，放到生产环境有四个致命隐患：

2.2 五步法#

业界标准做法可以概括为「双写 + 追平 + 校验 + 反向同步」，拆成五步：

第一步：增量订阅与位点标记（Prepare）。启动 Canal Deployer 订阅旧主表 Binlog，记录启动瞬间的 GTID 或 Binlog File + Position。增量 Binlog 可以挂载到 Kafka 等消息队列，也可以直接推给 Canal Adapter。增量链路先跑起来，且所有写入分表的逻辑必须幂等：INSERT INTO ... ON DUPLICATE KEY UPDATE，或基于 update_time 时间戳做版本判定，防止旧数据覆盖新数据。启动前还有一项 DDL 预检：源表若有承载状态值的 tinyint(1) 列，先改成 tinyint(4)——这类列在 Canal 解析阶段就会被折叠成 boolean，事后任何下游配置都救不回来（见第六节）。

第二步：存量数据迁移（Full Migration）。全量抽取严禁直接在主库执行，选择从库（Read Replica）或备份节点。工具用 DataX、mydumper 这类成熟的离线同步方案，或按主键 ID 做 Chunk 切片分段抽取，并限制抽取速率保护数据库。存量写入分表遇到主键冲突时用 INSERT IGNORE，或仅在存量数据时间戳更新时才执行更新，确保已被增量 Binlog 写入的新数据不被覆盖。

第三步：增量追平与数据校验（Validation）。存量导入完成后，让分表继续消费积压的 Binlog，直到延迟降至毫秒级。然后是校验，三个层次：

• 静态 Count & Sum：比对主表与分表在特定时间范围内的总条数，以及关键数值字段的和；
• 采样与全量 Hash：对主键取模采样，比对两边行记录的 Hash 值，条件允许就跑全量；
• 差异修复：运行独立的对比修复程序，扫描差异并自动生成补偿，直到一致率 100%。

第四步：灰度切流与反向同步（Cutover）。切流之前先搭好反向同步通道：用 Canal 订阅分表 Binlog，实时写回主表，让系统随时具备一键回滚的能力。切流本身分三步推进：

1. 影子读（Shadow Read）：应用部署新代码，写流量仍走主表，开启双读，对比主表与分表的读取结果，打日志监控差异；
2. 灰度写：按用户 ID、租户 ID 等路由键，把写流量逐步切到分表，1% → 10% → 50% → 100%；
3. 完全切流：所有读写彻底切到分表，观察 24~48 小时。发现异常，直接利用反向同步补齐的主表数据恢复流量。

第五步：链路收尾（Cleanup）。分表稳定运行一周、确认不再需要回滚之后：停止 Canal 正向与反向同步服务，下线主表同步链路相关组件，旧主表归档并释放数据库资源。

2.3 并发冲突在 SQL 层面根治#

存量抽取与增量消费并行，旧数据可能后到。根治办法是让写入 SQL 自带版本判定：

1
-- 增量 Binlog 写入分表：幂等 + update_time 守卫，状态只前进不后退
2
INSERT INTO logic_1 (id, base_id, f_key, state, updated_at)
3
VALUES (?, ?, ?, ?, ?)
4
ON DUPLICATE KEY UPDATE
5
  state = IF(VALUES(updated_at) >= updated_at, VALUES(state), state),
6
  updated_at = IF(VALUES(updated_at) >= updated_at, VALUES(updated_at), updated_at);
7

8
-- 存量数据写入分表：INSERT IGNORE，给增量让路
9
INSERT IGNORE INTO logic_1 (id, base_id, f_key, state, updated_at)
10
VALUES (?, ?, ?, ?, ?);

增量写入用 updated_at 做守卫；存量写入直接放弃冲突行。反向回写链路复用同一套幂等 SQL，还有一个附带的好处：MySQL ROW 模式的 Binlog 不会为「没有改变任何列值」的更新产生新事件，正向与反向链路即使互相触发，回环也会因为数据收敛而自然停止，不会无限放大。

2.4 回滚预案是方案的一部分，不是保险#

迁移方案的成败不只取决于上线是否顺畅，更取决于出问题时能否优雅退回。反向同步链路必须在灰度切流之前完全就绪。一旦分表出现未知死锁、慢查询拖垮业务这类紧急情况，把应用开关切回主表，业务分钟级恢复。

3.1 为什么需要聚合#

分表落地后，新的痛点跟着来：物理分表散落，原生跨表 UNION ALL 聚合查询性能极差；前端统计分析高频，不能挤占线上主库的 CPU 与 IO；业务要求数据变更后亚秒级反映到统计面板，物理删除也要实时同步。

方案是把 12 张分表实时汇聚到同一个 ES 索引 logic_all_index，查询压力全部甩给 ES，与主库彻底读写解耦。

3.2 架构与数据流转#

结合运维成本与扩展性，采用 Canal Deployer + Canal Adapter 的标准轻量组合。若后续写并发突破千级 QPS，可在中间引入 Kafka/RocketMQ 削峰填谷。

数据流转四步：

1. 捕获（Dump）：Deployer 伪装成 MySQL Slave 向 Master 发送 dump 协议，读取原始 Binlog；
2. 解析（Parse）：二进制日志解析为结构化的 FlatMessage，包含变更前后的列名与列值；
3. 映射（Transform）：Adapter 匹配正则 logic_.*，按 YAML 规则把 MySQL 字段转为 ES Document；
4. 加载（Load）：触发 Bulk 攒批机制，调用 ES REST API 批量写入。

3.3 先显式建 Mapping#

开启同步前必须在 ES 中显式创建 Mapping。f_key 是 varchar，动态 Mapping 会把它识别成 text，Terms Aggregation 直接报 Fielddata is disabled on text fields。日期字段同时声明三种格式兼容，避免源端时间格式差异导致解析失败：

1
PUT /logic_all_index
2
{
3
  "mappings": {
4
    "properties": {
5
      "id": { "type": "long" },
6
      "base_id": { "type": "long" },
7
      "f_key": { "type": "keyword", "doc_values": true },
8
      "state": { "type": "integer" },
9
      "created_at": {
10
        "type": "date",
11
        "format": "yyyy-MM-dd HH:mm:ss||strict_date_optional_time||epoch_millis"
12
      },
13
      "updated_at": {
14
        "type": "date",
15
        "format": "yyyy-MM-dd HH:mm:ss||strict_date_optional_time||epoch_millis"
16
      }
17
    }
18
  }
19
}

3.4 Adapter 映射配置#

在 Adapter 的 conf/es7/ 目录下添加映射配置 logic_table_es.yml：

1
dataSourceKey: defaultDS # 对应 application.yml 中的 MySQL 数据源配置
2
destination: example # 对应 Canal Deployer 的 instance 名称
3
groupId: g1 # 消费分组 ID
4
outerAdapterKey: es7_key # 对应全局配置中 ES 适配器的 Key
5
concurrent: true # 开启并发同步，提升吞吐量
6

7
dbMapping:
8
  database: my_biz_db # 数据库名称
9
  table: logic_.* # 【核心】正则匹配 logic_1 到 logic_12
10
  index: logic_all_index # 目标 ES 索引
11
  type: _doc # ES 7.x/8.x 统一填 _doc
12
  pk: id # 物理分表的主键列
13
  id: f_key # 【核心】ES 文档 _id：全局唯一业务键
14
  upsert: true # 存在则更新，不存在则插入
15
  commitBatch: 1000 # 达到 1000 条触发一次 Bulk 提交
16
  commitInterval: 1000 # 或每隔 1000ms 强制触发一次 Bulk 提交
17
  fields: # 字段映射字典（DB_Column : ES_Field）
18
    id: id
19
    base_id: base_id
20
    f_key: f_key
21
    state: state
22
    created_at: created_at
23
    updated_at: updated_at

几个关键决策：

• table: logic_.* 一条正则覆盖 12 张物理分表，后续扩表也不需要改同步配置；
• id: f_key 指定 ES 文档 _id。f_key 具备全局唯一性可以直接用；如果没有全局唯一业务键，必须用 CONCAT(base_id, '_', id) 之类的方式合成。12 张分表各自使用表内自增 ID，logic_1 和 logic_2 完全可能都有 id=100，直接拿 id 当 _id 会造成跨表数据互相覆盖，这是高危项；
• upsert: true 幂等覆写，配合一致的 _id 是全量与增量对接的基础（见 3.5）；
• commitBatch / commitInterval 双阈值攒批，先到先触发，避免单条写入打垮 ES。

3.5 存量 + 增量无缝对接#

Canal 作为 CDC 工具，默认读不到服务启动前已经存在的历史数据，全量需要单独走一条路。按数据量选：

• Adapter 内置 ETL（百万级以内）：部署完 Adapter 后直接调 REST 接口触发全量拉取，Adapter 自动扫描 12 张物理表并发抽取并 Bulk 写入 ES：

  1
  curl -X POST http://127.0.0.1:8081/etl/es7/logic_table_es.yml

• DataX / 离线脚本（千万级以上）：用 DataX 的 mysqlreader 多线程并发抽取 12 张表，elasticsearchwriter 批量写入 ES。

顺序上的铁律：先启动增量链路，再触发全量抽取。全量跑的这段时间里，线上业务还在持续产生 Binlog，必须防止全量的旧数据覆盖增量刚写入的新数据。两种机制：

• 机制 A：Upsert 覆写（首选，简单高效）。全量与增量使用完全一致的 ES _id（如 f_key），写入行为都是 Upsert。即使旧的全量数据后到达 ES，最新的增量 Binlog 变更也会随后再次覆写该 _id，保证最终一致性；
• 机制 B：外部版本控制（External Versioning）。ES 写入时指定 version_type=external，把 MySQL 的 updated_at 时间戳作为 version。ES 引擎拒绝任何版本号小于等于现有文档的写请求，物理级阻断「旧盖新」。

3.6 TINYINT 在 ES 侧的表现#

tinyint(1) 之外的 TINYINT 经 Canal 解析后是数字，到了 ES 侧最终表现为 Integer 还是 Boolean，完全取决于 Mapping 定义和 ES 的类型强转（Coercion）机制：

• Mapping 设为 "state": { "type": "integer" }，写入 1, 2, 3 正常存储；
• Mapping 设为 "is_deleted": { "type": "boolean" }，按 ES 默认 Coercion 规则，1、"1"、"true" 一律强转为 true，0、"0"、"false" 强转为 false。

tinyint(1) 是例外：它在 Canal 解析侧就被折叠成 boolean，原始状态值在到达 ES 之前已经丢失（实测案例见第六节），Mapping 定义得再对也救不回来。

如果需要把 TINYINT 状态码（1, 2）转义成可读文本（PENDING, SUCCESS），可以在 Adapter YAML 中编写 sql: 配置项，调用 MySQL 的 CASE WHEN 在读取阶段完成清洗。但要注意代价：配置了 sql: 的映射会让 Adapter 在增量同步时反查源库，写入量大的表会明显拖慢链路（见第六节）。

4.1 一源双送#

利用 Canal 的一源多送特性，Deployer 只解析一份 Binlog 镜像，Adapter 层同时驱动 ES Adapter 与 RDB (MySQL) Adapter：

切流期间，这条反向链路的回写目标是旧主表，充当回滚兜底；迁移稳定后，回写目标可以是独立的物理总表 logic_total，方便第三方 BI 报表工具直连或做逻辑归档。两种用途机制完全相同，下面以 logic_total 为例。

4.2 全局连接配置#

conf/application.yml 中同时挂载 ES 与 MySQL RDB 两个 Outer Adapter。重点在 MySQL 的 JDBC URL，必须追加类型对齐参数（原因见第五节）：

1
canalAdapters:
2
  - instance: example # Canal Deployer 实例名称
3
    groups:
4
      - groupId: g1
5
        outerAdapters:
6
          # --- 目标端 1：Elasticsearch ---
7
          - key: es7_key
8
            name: es7
9
            hosts: 192.168.1.100:9200
10

11
          # --- 目标端 2：MySQL 物理总表 ---
12
          - key: mysql_total_key
13
            name: rdb
14
            properties:
15
              jdbc.driverClassName: com.mysql.cj.jdbc.Driver
16
              # 【核心】必加 tinyInt1isBit=false&serverTimezone=Asia/Shanghai
17
              jdbc.url: jdbc:mysql://192.168.1.200:3306/total_db?useSSL=false&charset=utf8mb4&tinyInt1isBit=false&transformedBitIsBoolean=false&zeroDateTimeBehavior=CONVERT_TO_NULL&serverTimezone=Asia/Shanghai
18
              jdbc.username: root
19
              jdbc.password: 123456

4.3 RDB Adapter 映射配置#

conf/rdb/logic_table_mysql.yml：

1
dataSourceKey: defaultDS
2
destination: example
3
groupId: g1
4
outerAdapterKey: mysql_total_key
5
concurrent: true
6

7
dbMapping:
8
  database: my_biz_db
9
  table: logic_.* # 匹配源端 12 张分表
10
  targetDb: total_db
11
  targetTable: logic_total # 写入目标物理总表
12
  targetPk:
13
    f_key: f_key # 以 f_key 唯一键防重
14
  mapAll: true # 自动映射字段
15
  targetColumns:
16
    id: id
17
    base_id: base_id
18
    f_key: f_key
19
    state: state
20
    updated_at: updated_at

targetPk 用 f_key 防重，mapAll: true 自动映射同名字段，targetColumns 显式对齐关键列。

4.4 落地 SOP#

1. 提前建表：创建 ES Index Mapping（f_key 指定为 keyword）与 MySQL 总表 logic_total（建立唯一主键）；
2. 挂载增量：启动 Canal Deployer 与 Adapter，让增量同步链路先跑起来；
3. 触发全量：调用 Adapter 的 ETL 接口，或运行 DataX/SeaTunnel 脚本抽取历史数据；
4. 幂等对齐：依赖 ES / MySQL 的 Upsert 机制自动冲刷旧数据，保证最终一致性。

4.5 两条致命红线#

1. 总表主键冲突。12 张分表若存在自增 ID 冲突，写入总表必须使用 f_key 或 (base_id, id) 联合主键。严禁直接拿分表自增 id 作总表唯一主键，否则跨表数据互相覆盖。

2. 无限循环同步。若总表与源分表放在同一个 MySQL 实例中，必须在 Canal Deployer 的 instance.properties 里用正则严格圈定订阅范围、排除总表：

   1
   canal.instance.filter.regex = my_biz_db\\.logic_([1-9]|1[0-2])

   否则回写总表的动作产生新 Binlog，又被 Canal 捕获再回写，形成死循环。

1. EventParser：协议解析层#

这一层做三件事：

• 伪装 Slave：模拟 MySQL Replication 协议，与 Master 建立 Socket 连接并发送 Dump 请求。支持基于位点（mysql-bin.000003:4）和基于 GTID 两种注册方式。
• 网络解析：接收原始 Binlog 字节流，利用 canal.parse 模块解析为 MySQL 事件对象（QUERY / TABLE_MAP / WRITE_ROWS / UPDATE_ROWS / DELETE_ROWS 等）。
• 过滤与转化：将事件过滤并转码为 Canal 定义的 Entry 标准数据结构——基于 Protobuf 序列化，包含 Header（库名、表名、事件类型、执行时间、位点）和 StoreValue（行数据）。

其中容易被忽略的一步是 row 事件到列名的映射：row-based Binlog 里只有列的值没有列的名字，TABLE_MAP 事件只带 table_id。Canal 必须在本地缓存表结构（table meta），把 table_id 翻译成 schema + 列名，下游才能拿到「带字段名的行」。这也是为什么表结构变更（DDL）过程中要特别关注 Canal 的位点漂移和 meta 刷新。

2. EventSink：数据过滤与路由层#

• 正则过滤：根据配置的 canal.instance.filter.regex 进行表名/库名过滤，把不关心的库表在进缓冲前就丢弃，节省内存和网络。
• 归并与路由：在多 Master 或分库分表汇聚场景下，将多个 Parser 产出的数据进行时间戳归并或路由排序，保证下游看到的变更顺序合理。
• 数据加工：支持自定义拦截器（CanalEventDownStreamHandler）对 Entry 做额外补充或加解密。

3. EventStore：内存缓冲队列层#

这是整个管道里设计密度最高的模块。MemoryEventStoreWithBuffer 基于类似 LMAX Disruptor 的环形队列实现，内部维护三个指针：

三个指针把 RingBuffer 切成三段：[Ack, Get) 是已取出未确认的在途批次，[Get, Put) 是已写入未被读取的存量，[Put, Ack+BufferSize) 是可写的空闲区。

环形覆盖控制：当 Put - Ack >= BufferSize 时写入阻塞——注意阻塞的判定基于 Ack 而不是 Get。这意味着下游「取而不确认」同样会制造背压，Canal 用这个机制在内存占用和有界可靠之间取得平衡：要么下游正常消费释放空间，要么上游 Parser 停下来等，绝不静默丢数据。代价是下游长期不确认会让 RingBuffer 满、反压传导到 Binlog 拉取端。配合 MySQL 侧的 binlog_expire_logs_seconds（老版本为 expire_logs_days）还要盯紧：解析停滞太久、位点落后超过 Binlog 保留窗口，Master 把日志清了就再也追不回来了。

4. MetaManager：元数据与位点管理#

实时记录当前消费的 Binlog 文件名、Position 位点以及 GTID 信息，是断点续传的账本。支持多种存储介质：

• Memory：内存，进程重启即丢失，仅限开发调试；
• File：本地文件，单机部署够用；
• ZooKeeper：分布式协同，生产环境推荐——它同时是 HA 切换时新主恢复现场的依据。

位点的持久化时机值得留意：Canal 是按 store 已确认（Ack）的进度刷位点，而不是按 Parser 已拉取的位置。这决定了整体语义是至少一次——故障切换后从最后确认位点重放，可能重复，不会漏。

1. 方案 A：直接 TCP 协议通信（Netty）#

没有中间件的场景下，Adapter 充当 Canal TCP Client 直接连 Deployer。通信协议基于 Netty 传输 Protobuf 序列化的数据包，核心是一套 Get / Ack / Rollback 的拉取确认机制：

两个细节决定行为：

• getWithoutAck 而非 get：自动 Ack 模式下数据一旦发出位点就前进，下游处理失败即丢失；生产上必须用无确认拉取 + 显式 Ack，把释放内存的权利交给真正完成落盘的环节。
• Rollback 的粒度：rollback(batchId) 将 Get 指针重置回 Ack 位置。如果中间有多个已拉取未确认的批次，会一并回退重发，所以下游必须按主键做幂等（upsert），不能假设「一条数据只到达一次」。

2. 方案 B：基于 MQ 异步解耦（Kafka/RocketMQ）#

Deployer 开启 MQ 模式后自身充当 Producer，将解析好的 JSON 或 Protobuf 格式 Binlog 消息直接发送到 MQ Topic；Adapter（或任何自研消费者）作为 MQ Consumer 消费。

两种方案的取舍对比：

本质区别在于缓冲层的容量与持久性：方案 A 的缓冲是 Deployer 进程内的 RingBuffer——内存有限、重启即空，下游停滞的背压会一路顶到 Binlog 拉取端；方案 B 把缓冲外包给 MQ 的磁盘日志，容量近乎无限，且天然支持一份变更流被多个下游订阅组各自独立消费。代价是 Deployer 到 MQ 这一跳变成了 Push，发送失败时 Canal 的重试/降级策略需要显式配置（如 canal.mq.lazyRetry），否则可能丢消息。

另外一个必须关注的点是 MQ 模式下的顺序性：Kafka 只保证分区内有序。Canal 按指定 Key（canal.mq.dynamicKey / 分区 hash 策略，如按 PK 或表名）把消息路由到不同 Partition——只要路由键保证「同一行/同一表的变更恒定落同一分区」，行级顺序就有保障；如果按轮询分发，更新可能被乱序消费，目标端出现脏数据。

3. Adapter 内部的 ETL 映射与落盘#

Adapter 收到数据后，通过 YAML 规则文件（rdb / es / hbase 等 outerAdapter 配置）完成映射：

• 结构解析：将 Protobuf/JSON 转换为扁平化的 DTO 结构（Dml 对象：database、table、type、columns）。
• SQL 拼接 / API 调用：
  • 目标是 RDB：根据 insert / update / delete 三种处理器策略，自动拼接为 INSERT ... ON DUPLICATE KEY UPDATE 或 DELETE 等 SQL，通过连接池批量执行。目标表必须有主键，否则 update/delete 无法定位行。
  • 目标是 ES：将记录转为 JSON Document，调用 Bulk API 写入索引，用 PK 或自定义文档 id 保证幂等。

也就是说 Adapter 的落盘同样依赖「目标端幂等 + Canal 至少一次」这对组合，重复消息在 upsert 语义下被自然吸收。

1. Deployer 的分布式 HA：Instance 级主备选举#

先澄清一个高频误解：Canal Deployer 的分布式不是指单个 Instance 的并行切片解析。因为单个 MySQL 实例的 Binlog 是一个全局有序的日志流，任何下游要的都是一条不断链的顺序流，必须单线程串行解析——把 Binlog 切给多个节点并行解析，意味着要在下游重新归并定序，复杂度和风险都失控。

所以 Canal 的分布式指的是：基于 ZooKeeper 的 Instance 级别 Leader 选举与故障自动转移（Active-Standby）。

流程拆开看：

1. 抢锁：多台 canal-deployer 节点配置同一个 destination（如 instance_order），启动后尝试在 ZK 的 /canal/destinations/instance_order/running 路径下创建临时节点。ZK 保证同名节点只有一个能创建成功。
2. Active：抢锁成功者建立与 MySQL 的连接，开启 Binlog 消费链路，并持续把位点写入 ZK。
3. Standby：抢锁失败者对该节点注册 Watcher，处于热备挂起状态，不连 MySQL。
4. Failover：Active 节点宕机或与 ZK 会话超时，临时节点随之销毁；Standby 收到 Watch 变更后重新抢锁，新 Active 从 ZK 读取 MetaManager 记录的最后位点，从那一点接替 Binlog 解析。

临时节点（Ephemeral Node）+ Watch 这一对原语是整个方案的支点：会话生命周期即锁生命周期，不需要额外的心跳表或租约协议；故障检测（Session Timeout）和恢复通知（Watch）都在 ZK 内部闭环。代价也来自同一处——网络抖动导致 Active 与 ZK 会话超时但 MySQL 连接未断时，可能出现极短的双主窗口，依赖「同一 destination 在 MySQL 侧表现为两个 Slave 连接 + 位点覆盖」的幂等性兜底，这也是消费端坚持至少一次语义的原因之一。

多 Instance 时还有第三种角色：既非 Active 也非 Standby 的分配等待状态。当 admin/ZK 以分配模式（canal.deployer.getInstanceTimeOut / 任务均摊策略）管理时，destination 会被静态指派到指定机器，其余节点不参与该任务的选举。

2. Adapter 的分布式与伸缩#

消费端的扩展取决于上面选的协同方案：

• 直连 TCP 模式下的 Adapter HA：多个 Adapter 节点同样通过 ZK 做 Client 端的抢占式高可用——任一时刻只有一个 Adapter 在消费 Deployer，宕机后由 Standby 接管。仍然是单点消费，HA 解决可用性，不解决吞吐。
• MQ 模式下的分布式伸缩（高并发推荐）：Deployer 将 Binlog 按指定 Key（如 PK 或表名）Hash 路由到 Topic 的不同 Partition；集群部署多个 canal-adapter 节点组成同一个 Consumer Group，利用 MQ 的 Rebalance 机制实现多节点并行消费与分区容错，落盘吞吐随节点数近线性扩展。

1.1 agent 与沙箱之间的调用时序#

开发态下，AgentScope 通过标准 tool 协议驱动沙箱内的执行代理完成写文件、改代码、跑命令：

值得注意的是安全校验的位置。指令级过滤放在控制层，沙箱侧的执行代理在真正落地前再兜一次底。只在一处过滤不够：控制层的规则更新有延迟，而沙箱是唯一真正执行命令的地方。

2.1 沙箱池化与生命周期#

静态 PV 预挂载这条路走不通。每个用户一个 PV、Pod 启动时挂上，问题有两个：PV 挂载是 Pod 启动路径上的同步操作，冷启动时间不可控；ReadWriteOnce 的 PV 一旦挂到某个 Pod，就无法再被池里的另一个 Pod 挂载，复用直接冲突。

改成预热池加临时盘，持久化推迟到退场那一刻：

池子维持 N 个 ready Pod，N 按历史并发峰值配。分配一个沙箱只有两个动作：改 Pod label，在控制层内存里写入 app_id 到 Pod IP 的绑定。不碰存储、不重启进程，目标是把分配耗时压到 100ms 以内。

开发期间的读写全部落在容器本地的临时盘上。高频小文件场景，比如 node_modules 和 Vite 的 HMR 缓存，可以直接用 memory-backed emptyDir，省掉分布式文件系统的 I/O 锁开销。

退场是唯一一次持久化。用户断开或心跳超时（10 分钟）后，后台把临时盘打包上传 S3 或 MinIO，然后直接销毁 Pod。不在原 Pod 里做清理，因为残留的 dev server、僵尸进程和被 agent 改坏的环境变量，重来一次比修干净便宜。

这套设计最大的风险是：Pod 存活期间，用户的工作副本只有一份，就在容器本地。节点驱逐、OOM kill 或者上传失败，未同步的改动就没了。必须配一个兜底，在沙箱里跑定时增量同步，比如每 60 秒把 worktree 的 diff 推到对象存储，把丢失窗口从整个会话缩到最近一分钟。

2.2 基础镜像分层与依赖预热#

分层的目的是把耗时操作全部前移到构建期。

1
# Base Layer: 操作系统与编译工具链
2
FROM node:20-alpine AS base-runtime
3
RUN apk add --no-cache git bash curl python3 make g++ \
4
    && corepack enable \
5
    && corepack prepare pnpm@9.15.0 --activate
6

7
# Layer 1: Web IDE backend 及其依赖
8
FROM base-runtime AS editor-baked
9
WORKDIR /opt/ide
10
COPY ./vendor/web-editor-backend ./
11
RUN pnpm install --frozen-lockfile
12

13
# Layer 2: 脚手架模板与离线依赖 store
14
FROM editor-baked AS template-baked
15
WORKDIR /opt/templates
16
COPY ./templates/vite-react ./vite-react
17
COPY ./templates/nextjs-app ./nextjs-app
18
# 预跑安装，生成包含全量 cache 的镜像内 store
19
RUN cd ./vite-react && pnpm install --store-dir /root/.local/share/pnpm/store/v3
20
RUN cd ./nextjs-app && pnpm install --store-dir /root/.local/share/pnpm/store/v3
21

22
# Final Layer: 预热池运行镜像
23
FROM template-baked AS runner
24
EXPOSE 8080 3000
25
CMD ["/opt/ide/start.sh"]

base-runtime 里的 python3、make、g++ 是给 node-gyp 用的，不少包在 alpine 上要现场编译。editor-baked 把 IDE backend 装进镜像，沙箱起来就能提供编辑器。template-baked 预置 Vite、Next.js 等常用脚手架，并且预先跑一遍安装，把包塞进镜像内的 pnpm store。

agent 在沙箱里装依赖时，控制层的 tool 会强制给命令加上离线参数：

1
pnpm add <package> --prefer-offline --store-dir=/root/.local/share/pnpm/store/v3

命中预置 store 的包直接从本地硬链接，不走公网。这里有个副作用：--prefer-offline 只在 store 里存在对应版本时才生效，用户装了一个预置之外的版本，请求照样穿透到 registry。所以后面 NetworkPolicy 的白名单必须放行 npm 源，不能真的把出口全关死。

2.3 agent 执行的安全边界#

AgentScope 要在沙箱里跑大模型生成的任意 shell 命令，这是整个平台风险最高的地方。三层拦截：

指令安全包装器用黑白名单加 AST 解析做过滤，禁止 reboot、fdisk、curl http://169.254.169.254 这类访问云厂商元数据接口的动作。AST 解析比正则匹配难绕过，r""m -rf / 这种 shell 拼接能骗过正则，骗不过语法树。

容器级隔离靠 SecurityContext：

1
# Pod / 容器 spec 片段
2
securityContext:
3
  runAsNonRoot: true
4
  runAsUser: 1000
5
  readOnlyRootFilesystem: true
6
  allowPrivilegeEscalation: false
7
  capabilities:
8
    drop: ["ALL"]
9
  seccompProfile:
10
    type: RuntimeDefault

readOnlyRootFilesystem: true 要配合 emptyDir 使用，给 /workspace 和 /tmp 挂上可写卷，否则 pnpm 和 dev server 都写不了东西。

网络出口隔离屏蔽集群内部的 Service 网段，只放行公网 npm 镜像源和指定 API。这一层防的是沙箱里的代码横向摸到控制面，K8s API、Redis、内部 registry 全在这个网段里。

三层是递进关系，不是冗余：包装器拦意图，SecurityContext 拦权限，NetworkPolicy 拦出口。前两层被绕过时，第三层保证攻击者拿到的仍然是一个无法外联、也访问不到内网的空壳。

3.1 集群内构建：Kaniko#

部署触发后，控制面创建一个 K8s Job 跑构建。不在沙箱 Pod 里构建，也不依赖宿主机的 docker daemon。

用 Kaniko 而不是 docker-in-docker，是因为 dind 需要 privileged 容器，等于把节点交到用户代码手里。Kaniko 在普通 Pod 里解析 Dockerfile、逐层构建、直接推 registry，全程无特权。Next.js 侧配合 output: 'standalone'，产物自带最小 node_modules 子集，最终镜像能压到 80MB 左右。

1
apiVersion: batch/v1
2
kind: Job
3
metadata:
4
  name: build-job-app-123
5
spec:
6
  template:
7
    spec:
8
      containers:
9
        - name: kaniko
10
          image: gcr.io/kaniko-project/executor:v1.20.0-debug
11
          args:
12
            - "--context=s3://app-code-bucket/app-123.tar.gz"
13
            - "--dockerfile=Dockerfile.prod"
14
            - "--destination=registry.internal/apps/app-123:v1.0.0"
15
            - "--cache=true"
16
            - "--cache-dir=/cache"
17
          volumeMounts:
18
            - name: kaniko-cache
19
              mountPath: /cache
20
      restartPolicy: Never
21
      volumes:
22
        - name: kaniko-cache
23
          persistentVolumeClaim:
24
            claimName: kaniko-cache-pvc

--cache=true 配一个共享 cache 卷，让同一应用的重复部署只重建变化的层。要注意这个 PVC 是 ReadWriteOnce，多个构建 Job 并发时会互相争抢。构建量上来之后，要么换成 ReadWriteMany 的存储，要么改用 --cache-repo 把层缓存推到远端 registry，让 Job 之间彻底无共享。

3.2 网关的请求缓冲#

scale-to-zero 的代价是第一个请求要等 Pod 起来。网关的做法是把这段等待藏在连接里，而不是返回错误页让用户自己重试。

请求进来，网关按 path 解析出 app_id，查 Redis 拿副本数。副本数为 0 就触发扩容，同时挂住当前连接，轮询 Pod 的健康检查端点，就绪之后再把缓冲的请求转发过去。对客户端来说，这只是一次比较慢的响应。

1
func (g *Gateway) HandleRequest(w http.ResponseWriter, r *http.Request) {
2
    appID := extractAppID(r.URL.Path)
3
    podIP, exists := g.lookupActivePod(appID)
4

5
    if !exists {
6
        // 1. 触发 K8s 扩容
7
        err := g.k8sClient.ScaleDeployment(appID, 1)
8
        if err != nil {
9
            http.Error(w, "Failed to scale app", http.StatusInternalServerError)
10
            return
11
        }
12

13
        // 2. 挂起当前连接，进入健康检查等待队列
14
        ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
15
        defer cancel()
16

17
        readyPodIP, err := g.waitForPodReady(ctx, appID)
18
        if err != nil {
19
            http.Error(w, "Application Cold Start Timeout", http.StatusGatewayTimeout)
20
            return
21
        }
22
        podIP = readyPodIP
23
    }
24

25
    // 3. 转发请求
26
    g.proxyToPod(w, r, podIP)
27
}

15 秒超时是经验值：Node 应用从调度到 listen 通常 3~8 秒，留一倍余量。超时之后返回 504 而不是继续挂着，因为再等下去客户端自己也会超时，不如明确告诉用户失败了。

有个细节容易漏：挂起期间要限制并发唤醒。同一个冷应用的 100 个并发请求不该触发 100 次 ScaleDeployment，网关侧要按 app_id 做 singleflight，只有第一个请求负责唤醒，其余等同一个结果。

3.3 Janitor：阶梯式回收#

回收同时看两个信号，应用空闲了多久，集群还剩多少资源。

1
import time
2

3
class PodLifecycleJanitor:
4
    def __init__(self, k8s_client, metrics_client, redis_client):
5
        self.k8s = k8s_client
6
        self.metrics = metrics_client
7
        self.redis = redis_client
8

9
    def run_eviction_loop(self):
10
        while True:
11
            cluster_mem_percent = self.metrics.get_cluster_memory_usage()
12
            active_apps = self.k8s.get_running_serverless_apps()
13
            now = time.time()
14

15
            for app in active_apps:
16
                last_active = self.redis.get_last_access_timestamp(app.id)
17
                idle_time = now - last_active
18

19
                # 策略 1: 超长空闲强制回收（硬阈值 30 分钟）
20
                if idle_time > 1800:
21
                    self.k8s.scale_to_zero(app.id)
22
                    continue
23

24
                # 策略 2: 资源高压抢占式回收（软阈值 10 分钟 + 内存 > 85%）
25
                if cluster_mem_percent > 85.0 and idle_time > 600:
26
                    self.k8s.scale_to_zero(app.id)
27
                    # 回收一个就重新读一次水位
28
                    cluster_mem_percent = self.metrics.get_cluster_memory_usage()
29

30
            time.sleep(30)

两条策略：空闲超过 30 分钟无条件回收到 0；集群内存超过 85% 时把空闲阈值降到 10 分钟，回收一个再重读一次水位，够了就停。第二条是抢占式的，目的是在节点压力上来之前先腾地方，而不是等 kubelet 开始驱逐，那时候被赶走的可能是活跃应用的 Pod。

30 秒的巡检周期是在回收延迟和 API 压力之间取的折中。应用数量多的时候，每轮遍历要发 N 次 Redis 查询加若干次 metrics 查询，这个循环本身会变成负载。规模上来之后应该改成事件驱动，网关在处理最后一次请求时写一个延迟任务，而不是靠轮询全量扫描。

4.1 CRIU：把初始化状态存成快照#

思路是沙箱 Pod 跑完初始化（框架加载、模块解析、端口 listen）之后，用 CRIU 把进程树的内存状态 dump 到 S3；新连接进来时不重启进程，直接 restore。理论上能把 1~3 秒的冷启动压到 100ms 以内，因为跳过的正是最耗时的那一段。

实际约束不少。CRIU 需要内核开启 CONFIG_CHECKPOINT_RESTORE；dump 出来的状态要跟目标节点的内核和 glibc 版本对得上，跨节点漂移因此受限；Node 进程持有的 socket、epoll fd、timer 在 restore 之后都要重建，dev server 的监听端口和已建立的 WebSocket 尤其麻烦。比较务实的路径是先拿生产侧的 Next.js standalone 进程试，它的 fd 状态比沙箱里的 dev server 简单得多。

4.2 Firecracker：换成独立内核#

容器隔离的本质是共享宿主机内核，一个内核提权漏洞就能穿透到节点和其他租户。Firecracker 用 KVM 给每个沙箱一个独立内核，启动开销约 125ms，比传统虚拟机低两个数量级。在”允许 agent 执行任意 shell”这个前提下，这是比 SecurityContext 强得多的保证。

前提是节点要有 /dev/kvm。GKE、EKS 的标准节点池不暴露嵌套虚拟化，得单开裸金属节点池，成本模型会变。工程上一般不直接对接 Firecracker API，而是走 Kata Containers，让它以 RuntimeClass 的形式接进现有调度体系。另外 rootfs 和网络要从 OCI 镜像模型换成 virtio 模型，Kaniko 的产物需要一个转换层。

4.3 Wasm：把一类应用从 Pod 里拿出来#

没有原生依赖、逻辑简单的 API 和 SSR 应用，构建期多产一个 Wasm target，运行时直接丢进网关侧的 WasmEdge，连 Pod 都不用起。冷启动是微秒级，常驻成本接近零。

适用范围窄是它主要的问题。node:fs、child_process、原生 addon 在 Wasm 运行时里覆盖不全，任何用了数据库驱动的二进制、sharp、esbuild 原生版本的项目都跑不了。可行的做法是在构建期做能力探测，依赖图里没有原生模块才走 Wasm 通道，否则回落到现在的 Pod 方案。两条通道会长期并存。

3.1 组织思想：DDD 分层#

概念上把项目知识分成业务、代码资产、约束、架构四个维度；落到目录时改用 DDD 的组织方式，分三级：业务域 → 域下业务线 → 跨域业务。

需求进来先归域，再定位到具体的业务线文档。业务域枚举同时也是影响分析的索引。

3.2 结构思想：索引 + 渐进式披露#

知识库按索引加渐进式披露（progressive disclosure）组织，避免一次性把全部内容灌进上下文：

1
根 INDEX.md（全局导航 + 快速入口 + 写作规范 + 已知缺口）
2
    └── 子目录 INDEX.md（本地导航）
3
            └── 叶子文档（具体知识）

配套的写作规范：每个目录必须有 INDEX.md；内部链接用相对路径；源码引用用项目根绝对路径；涉及时效的内容标注分析日期；一篇一主题，超过 300 行考虑拆分；推断的内容显式标出来。

3.3 效果与边界#

效果是 AI 接需求后按「根索引定方向 → 子索引找文档 → 叶子文档读细节」的路径检索，影响范围分析的准确率和速度都明显提升。顺带的好处是知识库同样服务人，新人上手成本降了一截。

但边界也清楚：知识库管的是 AI 知道什么，不管 AI 怎么做。开发流程仍然靠 agent 的内置行为。

4.1 agent 的内置流程不够用#

agent 的内置流程是通用的，不长着我们的开发经验：不做影响范围分析就直接动手，不确认方案就开始实施，改完不 review，也不回写知识库。结果和阶段一一样，不断纠正。

于是把实际做需求时的那套动作提炼成 workflow，写进 AGENTS.md，让 agent 默认按它执行。AGENTS.md 同时承载知识库的使用方式和业务开发约束，比如接口规范、常量复用、统一消息体这些。

4.2 第一堂课：Spec 职责膨胀，以及行业给的答案#

流程跑起来后，瓶颈挪到了产物上：spec 把「实现目标」和「实现步骤」混在一起写。需求一大，文档膨胀、逻辑混杂，agent 照着巨型 spec 一次性全量生成代码，出错率和调试成本都高。

当时找到的行业答案是 SDD（Spec-Driven Development）：把「做什么 / 约束什么（契约）」与「具体怎么做（执行）」严格分开。典型形态是三件套：

1
PRD (业务意图: What & Why)
2
 └── [拆解]
3
      ├── spec.md    技术与架构契约：模型变动、API、数据契约（严禁包含实现步骤）
4
      ├── DESIGN.md  视觉契约：设计 Token、组件形态、样式红线（仅含 UI 的项目）
5
      └── tasks.md   原子化任务清单：带依赖关系的 CheckList，单任务限制在 1~3 个文件

这套答案很有价值，但它是一份通用模板。移植时要回答的问题不是照抄哪些文件，而是我的项目到底需要哪些机制。

4.3 裁剪之后：当时实际运行的 spec 形态#

几轮试错，第一版落地成了单一 spec 文档、八段结构，workflow 每执行一次生成一份：§0 Workflow 配置 / §1 需求描述 / §2 影响分析 / §3 实施方案 / §4 验收标准 / §5 实施记录 / §6 Code Review / §7 总结。

裁掉三件套，理由有三条：

1. DESIGN.md 没有使用场景，这是个纯后端系统。但「用机器可读的清单锁死红线」这个思路保留了，落在 review 的维度清单上。
2. 实现步骤留在 §3，不拆独立的 tasks.md。契约和步骤分节就够，拆成两个文件反而多出一份同步负担。
3. spec 还担了一个提案里没提到的职责：流程状态的唯一持久化载体。这个职责从哪来的，见下一节。

4.4 第二堂课：流程不可观测、不可回溯#

workflow 进了 AGENTS.md，agent 确实按流程走了，但新的麻烦跟着来：

• 不可观测：agent 走到哪一步了，每一步的输入输出是什么，对话流里看不清；
• 不可回溯：一周后回头看某次改动，当时的需求理解、方案取舍、踩过的坑全丢了，只剩代码。

对应的办法是把 workflow 建模成状态机：P0 项目上下文解析 → P1A 需求采集 → P1B 影响分析 → P2A 环境采集 → P2B 约定与开发模式 → P2C 编写 spec → P3 实施 → P4 review → P5 归档 → P6 知识库反哺 → DONE，spec 文档就是状态机的持久化状态。几个关键机制：

• Checkpoint：P2C → P3 边界强制暂停。实施是不可逆操作，必须由开发者显式说「继续」。
• 回退规则：一次只能回退一个 phase，保留上游产出，回退原因写入实施记录。
• 打断规则：内置打断（比如在主干分支上直接动手时中断，要求先建分支），加外部打断（需求变更触发重置，可暂停、可恢复）。
• 转移通知：每次状态转移输出一份统一格式的交接单：已完成什么、现在在哪、下一步做什么、需要开发者做什么。
• 会话恢复：会话中断后，读 spec 里的 checkpoint 快照就能恢复 workflow 位置，不依赖对话记忆。
• 防死循环：所有循环有界（追问 ≤3 轮、修订 ≤3 轮），每轮必须收敛，超限熔断上报。

4.5 运行数据#

那段时间一个月里沉淀了 23 份 spec，覆盖 feat / fix / refactor 三类需求，其中既有知识库建设本身，也有 workflow 自己的演进，流程工具在迭代它自己。附带的好处落在「踩坑记录」这一节：像「全文档 grep 验收时宽正则会误匹配同名文件，得用精确模式」这种细节，写进去一次，就不会踩第二次。

5.1 动机#

workflow 在 AGENTS.md 里跑了一阵，暴露两个问题：

1. 流程定义与项目耦合。状态机、转移规则是通用内容，却和项目专属约束混在一起，没法复用到别的项目。
2. 常驻加载成本。流程规格与日俱增，单文档一度 800+ 行，随项目入口文件每次会话常驻上下文，而绝大多数日常小改动根本用不上。

所以把 workflow 内化成 skill（.agents/skills/sdd-workflow/），改成显式触发，一句「按 SDD 流程」或「走 sdd」才启用。日常小改动不再背着流程跑。

5.2 skill 的结构：常驻规格 + 按需加载#

OpenAI 和 Anthropic 在 Agent Skills 开放标准里给的几条原则，和这个设计正好对上：把 skill 当成写给「高智商但缺系统上下文的初级程序员」的 API 文档（ACI）；内容分层、按需加载（渐进式披露）；把频繁连用的多步操作合并成一个高层工作流，而不是堆一堆原子能力（少即是多）。落地结构：

5.3 扩展点：隐藏文件承载项目适配#

skill 是通用的，项目却各有各的特点。扩展点放在项目根目录的 .sdd-workflow/project-context.md，按块声明适配信息：知识库位置（根路径/索引/约定目录）、产物存储（需求目录容器/需求索引/归档根）、业务域枚举、横切关注点 checklist、Review 维度、反哺判定标准。

P0 阶段加载这份清单，没声明的项退回 skill 内置的通用默认值，比如「跨服务调用、数据库变更、API 契约变更、配置变更、新增枚举常量、异步任务、定时任务」这七项通用横切检查。通用流程在 skill 里，项目特性在隐藏文件里。

5.4 同期改进：追问的纪律#

需求采集阶段加了两条规矩，把无依据提问和低效多轮交互砍掉了大半：

• 知识检索阶梯：先查知识库，再查代码，最后才问人。可查证的事实禁止提问。
• Grilling 追问：每轮最多 3 题，只问决策与业务语义、不问事实，每题附推荐答案，3 轮熔断进「开放问题」。

Install#

首先安装 rustup ，该工具是一个跨平台的用于管理不同 Rust 及其工具链组件版本的官方工具。

终端执行以下脚本（不要使用 sudo 安装）：

1
$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

成功安装后终端会提示这个：

1
Rust is installed now. Great!

在安装过程中可能会遇到文件写入权限不足导致失败的情况，这是因为 rustup 的安装脚本会检测并修改当前用户家目录下可能存在的配置文件，比如 ~/.profile、~/.base_profile、~/.baserc、~/.zshenv（zsh），如果权限不足可以执行以下命令调整配置文件权限：

1
sudo chown $(whoami) ~/.profile

MacOS 现在默认使用 zsh，其他配置文件如果不需要可以删除，也可以调整权限后保留。

最后重启当前 shell，重新加载 PATH。

Rustup 的 metadata 和 toolchain 都会放在 /Users/${username}/.rustup 目录下，当然也可以通过修改环境变量 RUSTUP_HOME 来调整位置。

Cargo 的家目录在 /Users/${username}/.cargo 目录下，环境变量为 CARGO_HOME。

cargo、rustc、rustup 和其他工具都在 Cargo 的 bin 目录中，即 ${CARGO_HOME}/bin 。

执行完安装操作后，相关命令会自动添加到 PATH 路径中，如果需要卸载 rustup 可以执行 rustup self uninstall，上面的操作都会被移除。

成功安装 rustup 后，还需要一个 linker（链接器）才可以将编译产物打包为一个文件，比如 macos 的 ld，如果没有安装则可以通过以下命令安装 xcode：

1
$ xcode-select --install

Linux 平台一般是 GCC 或 Clang，根据系统发行版本选择合适的 linker。

使用以下命令验证是否正确安装 Rust：

1
$ rustc --version
2
rustc 1.93.0 (254b59607 2026-01-19)

Updating And Uninstalling#

使用 rustup 安装和管理 Rust 时，升级版本或卸载操作非常简单，只需执行以下命令：

1
# 升级到最新版本
2

3
$ rustup update
4

5
# 卸载 Rust 和 rustup
6

7
$ rustup self uninstall
8

9
# 查看本地的 Rust 文档
10

11
$ rustup doc

Install LazyVim#

https://www.lazyvim.org/installation

1、先备份当前 neovim 的配置

1
# required
2

3
mv ~/.config/nvim{,.bak}
4

5
# optional but recommended
6

7
mv ~/.local/share/nvim{,.bak}
8
mv ~/.local/state/nvim{,.bak}
9
mv ~/.cache/nvim{,.bak}

2、然后克隆 LazyVim 提供的预先配置好的 Neovim 的配置模版

克隆模版仓库

1
git clone https://github.com/LazyVim/starter ~/.config/nvim
2

3
# 移除 git 相关的目录
4

5
rm -rf ~/.config/nvim/.git

3、启动 Neovim

1
nvim

执行命令后会进入 lazy.nvim 的管理页面，开始下载 LazyVim 预设的插件

Hello World#

rust 代码文件以 .rs 为后缀，如果文件名有多个单词，推荐以下划线连接多个单词。

新建目录，最后在 hello_world 文件夹下新建 main.rs 文件：

1
$ mkdir ~/projects
2
$ cd ~/projects
3
$ mkdir hello_world
4
$ cd hello_world
5

6
# 可以使用 IDE，也可以使用编辑器，这里以 nvim 为例
7

8
$ nvim main.rs
9
fn main() {
10
println!("Hello, world!");
11
}
12

13
$ rustc main.rs
14
$ ./main
15
Hello, world!

几个注意点：

• Rust 代码文件后缀是 rs

• main 函数很特殊

• 每个 Rust 文件中叫做 main 的函数是第一个被执行的

println! 叫做 Rust macro，如果去掉 ! 就是调用一个函数，注意宏和函数的规则不一定一样，Rust macro 是一种用来扩展 Rust 语法的代码。

rustc 是 Rust 的编译器，能将 rs 文件编译输出为一个可执行文件，Rust 是一种 ahead-of-time compiled language（预编译语言），需要先将代码进行编译，然后才能运行程序，这一点和其他动态语言不太一样，比如 Ruby、Python、JavaScript。

如果代码或项目不太复杂，rustc 已能满足需求，如果项目较为复杂，可以使用 cargo。

Create a Project with Cargo#

创建 cargo 项目：

1
[projects]$ cargo new hello_cargo
2
[projects]$ cd hello_cargo
3
[hello_cargo]$ ls
4
Cargo.toml src

使用 cargo new 命令会默认安装内置的 binary application 模版创建项目，包含 toml 和 src/main.rs 文件 TOML （Tom’s Obvious, Minimal Language）格式的文件是 Cargo 使用的项目配置文件。

1
[hello_cargo]$ cat Cargo.toml
2
[package]
3
name = "hello_cargo"
4
version = "0.1.0"
5
edition = "2024"
6

7
[dependencies]

[package] 块下面可以写 package 级别的配置，这里配置了项目的 name、version 和 Rust 的 edition。

最后一行 [dependencies] 后面会列出来项目使用的依赖，在 Rust 中代码库也被叫做 crates，目前这个项目还没有使用其他 dependencies。

接着可以查看 src/main.rs 文件：

1
[hello_cargo]$ cat src/main.rs
2
fn main() {
3
println!("Hello, world!");
4
}

Cargo 会自动生成 hello world 程序，和前面编写的代码相比，使用 Cargo 生成的项目，代码都在 src 目录下，同时也会生成一个 Cargo.toml 文件。还有一个快速生成 Cargo.toml 文件的方式就是执行 cargo init 命令，它会自动生成 toml 文件。

Building and Running a Cargo Project#

输入以下命令来打包项目：

1
[hello_cargo]$ cargo build
2
Compiling hello_cargo v0.1.0 (/.../projects/hello_cargo)
3
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s

该命令会构建项目输出可执行文件 target/debug/hello_cargo，放到 debug 目录下是因为默认的构建就是 debug build，可以直接执行该文件：

1
[hello_cargo]$ target/debug/hello_cargo
2
Hello, world!

第一次执行 cargo build 命令，会产生一个 Cargo.lock 文件，该文件的作用是用于跟踪项目使用的 dependencies 的版本信息，我们无需手动操纵该文件内容，它由 cargo 来管理。

上述操作是先 build 再执行文件，也可以通过 cargo run 一个命令来实现：

1
[hello_cargo]$ cargo run
2
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
3
Running `target/debug/hello_cargo`
4
Hello, world!

除此之外，Cargo 还提供了 cargo check 命令用来检查项目代码是否可以正常编译，因为 Rust 编译对代码安全有严格要求。

当项目变得复杂时，可以周期性执行 cargo check，在检查代码问题的时候也会生成一些中间产物放在 target 目录下，然后在执行 cargo build，这样 build 时就可以利用 target 下的资源来加速构建，不过这也会产生一些问题，target 目录会变得很大。

到目前为止已经了解了一下几个命令：

• cargo new 新建项目
• cargo build 构建项目
• cargo run 可以在构建后立即执行
• cargo check 可以对代码做检查，而不产生可执行文件
• cargo 默认会将构建结果放在 target/debug 目录下，而不是作为项目代码

Building for Release#

当项目开发完毕，需要进行发布，此时应该执行 cargo build —release 命令，在 build 时加上 —release 参数，最后生成的文件会放在 target/release 目录下，注意在开发阶段 build 的产物放在 target/debug 目录。

release 构建时间会比 debug 要长，因为内部做了一些优化操作，可以让程序运行的更快，这是因为在开发阶段期望能快速构建来验证结果，而发布阶段则希望程序性能更好。

Leveraging Cargo’s Conventions#

对于简单的项目，使用 Cargo 带来的收益相比使用 rustc 其实没提升多少，但是随着项目变得复杂，文件变得更多且引入其他依赖，此时使用 Cargo 来管理项目就会变得更方便。