Apache Teaclave 0.6.0 快速入门与集成示例

本文面向首次接触 Apache Teaclave 0.6.0 的工程师，从源码构建到首个机密计算任务跑通提供最快路径，并给出 Python SDK 集成、多方隐私求交任务、WASM 密态载荷与 teaclave_cli 文件加解密管线的实测集成示例。

Apache TeaclaveApache Teaclave2026/10/15

Apache Teaclave 0.6.0 快速入门与集成示例

目标：以最短路径完成 Teaclave 0.6.0 源码构建、服务启动与首个机密计算任务，并通过 Python SDK 与 WASM 载荷两种方式集成自定义计算逻辑，全部步骤在 SGX 模拟模式实测通过。

Teaclave 是 Apache 顶级项目的机密计算平台：函数在 enclave（飞地）内执行，数据以密钥管控方式进出，支持多方协作审批。本文基于 legacy 分支 65886ec（2025-07-17）实测。无 SGX 硬件时，官方模拟模式（SGX_MODE=SW）提供与硬件一致的软件接口，是入门与功能验证的推荐路径。

一、环境信息

项目值
操作系统Ubuntu 22.04 LTS（x86_64，12 vCPU / 39 GB 内存）
平台版本0.6.0（legacy 分支 65886ec，最后发布 tag v0.6.0 于 2023-06-12）
构建模式SGX 模拟模式（-DSGX_SIM_MODE=ON -DTEST_MODE=ON -DOFFLINE=ON）
工具链gcc-9 9.5.0 / rustc 1.66.0-nightly（5c8bff74b 2022-10-21）/ SGX SDK 2.17.101.1
源码路径/root/teaclave，产物 /root/teaclave/release
构建产物规模release 目录 3.9 GB（含 7 个服务、3 个测试 enclave、CLI 与示例）

💡 技术拓展：Teaclave 生态当前的形态——主仓库已转型为 TLP（顶级项目）入口，活跃开发在子项目中进行（Teaclave SGX SDK 最新 tag v1.1.6、TrustZone SDK、Java TEE SDK、teaclave-crates）；本文使用的 FaaS 平台代码位于主仓库 legacy 分支，官方声明不再活跃维护，其价值在于完整的任务调度、多方审批与密态函数体系，适合作为机密计算平台的学习基线与二开参考。

二、前置条件与构建

2.1 依赖清单（Ubuntu 22.04 实测）

apt-get install -y build-essential ocaml ocamlbuild automake autoconf libtool \
  libssl-dev libcurl4-openssl-dev libprotobuf-dev pkg-config cmake git wget \
  protobuf-compiler gcc-9 g++-9 python-is-python3

四个易踩坑项实测说明：gcc-9（Ubuntu 22.04 默认 GCC 11 编译 rust-sgx-sdk 固定子模块的 C++ 源码报「指针与整数比较」错误）；protobuf-compiler（prost-build 运行需要 protoc）；python-is-python3（CMake 解析脚本调用 python 命令，缺失时配置末尾报 sgxapp-NOTFOUND）；另有 OpenSSL 1.1 兼容层需求见 2.3。

2.2 SGX SDK 与 Rust 工具链

# SGX SDK 2.17.1（模拟库随包附带）
cd /root
wget https://download.01.org/intel-sgx/sgx-linux/2.17.1/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.17.101.1.bin
chmod u+x sgx_linux_x64_sdk_2.17.101.1.bin
printf "no\n/opt\n" | ./sgx_linux_x64_sdk_2.17.101.1.bin
ls /opt/sgxsdk/lib64 | grep -c sim    # 实测输出 8

# 固定 Rust 工具链（CMake 强制要求该版本）
curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none
source $HOME/.cargo/env
rustup toolchain install nightly-2022-10-22 --profile minimal
rustup component add rust-src rustfmt clippy --toolchain nightly-2022-10-22

2.3 OpenSSL 1.1 兼容层

Ubuntu 22.04 的 OpenSSL 3.0 缺少 SGX SDK 2.17.1 模拟库所需的 libcrypto.so.1.1 版本化符号，实测链接服务时报 undefined reference to EVP_sha1@OPENSSL_1_1_0 等错误。需源码构建 OpenSSL 1.1 并注册到动态链接器：

cd /usr/local/src
curl -L -o openssl-1.1.1w.tar.gz https://github.com/openssl/openssl/releases/download/OpenSSL_1_1_1w/openssl-1.1.1w.tar.gz
tar xf openssl-1.1.1w.tar.gz && cd openssl-1.1.1w
./config shared --prefix=/opt/openssl-1.1 --openssldir=/opt/openssl-1.1/ssl
make -j12 && make install_sw
echo /opt/openssl-1.1/lib > /etc/ld.so.conf.d/openssl-1.1.conf && ldconfig

2.4 源码获取、预取与配置

cd /root
git clone --depth 1 --branch legacy https://github.com/apache/incubator-teaclave.git teaclave
cd teaclave && git submodule update --init --recursive
git log -1 --format="%h %ad" --date=short        # 实测输出 65886ec 2025-07-17

source /opt/sgxsdk/environment
mkdir -p build && cd build && make prep           # 生成 cargo 工作区清单

cd cmake_tomls
cargo fetch --manifest-path unix_app/Cargo.toml
cargo fetch --manifest-path sgx_untrusted_app/Cargo.toml
cargo fetch --manifest-path sgx_trusted_lib/Cargo.toml

串行预取可避免并行构建时多 cargo 进程争抢 git 依赖库导致的 object not found 错误（实测遇到并确认该问题与修复方式，详见安装指南 FAQ）。

cd /root/teaclave/build
cmake -DTEST_MODE=ON -DSGX_SIM_MODE=ON -DOFFLINE=ON \
      -DCMAKE_C_COMPILER=gcc-9 -DCMAKE_CXX_COMPILER=g++-9 ..
cmake -DTEST_MODE=ON -DSGX_SIM_MODE=ON -DOFFLINE=ON \
      -DCMAKE_C_COMPILER=gcc-9 -DCMAKE_CXX_COMPILER=g++-9 ..
grep -E "SGX_SIM_MODE|TEST_MODE|OFFLINE" CMakeCache.txt

必须执行两次：首次配置会因子模块初始化触发内部重配置并丢弃 -D 选项（实测 SGX_SIM_MODE 落回 OFF），第二次才落定为 ON。实测缓存确认：

OFFLINE:BOOL=ON
SGX_SIM_MODE:BOOL=ON
TEST_MODE:BOOL=ON

2.5 全量构建

make -j12

实测退出码 0，完成 601 个 crate 与全部 enclave 编译，产物清单：

release/cli/teaclave_cli                              命令行工具
release/services/teaclave_{authentication,storage,access_control,
  management,scheduler,frontend,execution}_service   七个服务进程
release/services/*_enclave.signed.so                  对应 enclave（模拟签名）
release/tests/teaclave_{unit,functional,integration}_tests  测试 enclave
release/bin/teaclave_execution_service_libos          LibOS 执行器
release/tools/teaclave_sgx_tool                       enclave 信息工具

构建目录 32 GB（debug 符号），release 产物 3.9 GB，磁盘预留建议 50 GB 以上。CentOS 8 环境的构建差异（EOL 源、CA 证书、wget 预置等）见《CentOS 8 安装 Apache Teaclave 指南》。

三、启动服务与首个机密计算任务

3.1 服务启动

source /opt/sgxsdk/environment
export TEACLAVE_PROJECT_ROOT=/root/teaclave
export SGX_MODE=SW
export RUST_LOG=info
export AS_SPID="00000000000000000000000000000000"
export AS_KEY="00000000000000000000000000000000"
export AS_ALGO="sgx_epid"
export AS_URL="https://api.trustedservices.intel.com:443"

cd /root/teaclave/release/services
nohup ./teaclave_authentication_service > /tmp/auth.log 2>&1 &
nohup ./teaclave_storage_service > /tmp/storage.log 2>&1 &
nohup ./teaclave_access_control_service > /tmp/ac.log 2>&1 &
sleep 6
nohup ./teaclave_management_service > /tmp/mgmt.log 2>&1 &
nohup ./teaclave_scheduler_service > /tmp/sched.log 2>&1 &
sleep 6
nohup ./teaclave_frontend_service > /tmp/frontend.log 2>&1 &
nohup ./teaclave_execution_service > /tmp/exec.log 2>&1 &
sleep 5
ss -tln | grep -E ":(7776|7777|17776|17777|17778|17779|17780) "

实测七个端口全部监听。AS_* 占位值仅模拟模式有效（认证禁用）。

3.2 运行官方回显示例

pip3 install pyopenssl toml cryptography requests grpclib grpcio grpcio-tools
cd /root/teaclave/examples/python
SGX_MODE=SW PYTHONPATH=/root/teaclave/sdk/python python3 builtin_echo.py "Hello, Teaclave!"

实测输出：

[+] login
[+] registering function
[+] creating task
[+] invoking task
[+] getting result
[+] done
[+] function return:  b'Hello, Teaclave!'

请求经认证服务登录换令牌、前端服务注册函数并创建任务、调度服务派发、执行服务在 enclave 内运行 builtin echo 函数、结果按原链路返回。Python 3.10 环境需为 sdk/python/teaclave.py 的 NPN 兼容防护补充 AttributeError 捕获（详见进阶实战文档 2.2 节）。

四、集成示例一：Python SDK 定制任务

Python SDK（/root/teaclave/sdk/python/teaclave.py，单文件纯 Python 实现）是与平台集成的主通道。最小集成封装：

from teaclave import AuthenticationService, FrontendService

def login(user_id, user_password):
    with connect_authentication_service() as client:
        return client.user_login(user_id, user_password)

def frontend(user_id, token):
    client = connect_frontend_service()
    client.metadata = {"id": user_id, "token": token}   # 每次请求携带
    return client

注册函数与调用任务的完整实测代码见 3.2 节 builtin_echo.py；多方任务（双方各自注册数据、审批、取结果）的实测代码路径为 examples/python/builtin_ordered_set_intersect.py，实测输出：

[+] user0 approving task
[+] user1 approving task
[+] user0 invoking task
[+] User 0 result: 3 common items
[+] User 1 result: 3 common items

集成要点实测确认：多方任务必须全部数据所有者 approve 后才能执行；各方仅见自己的结果文件与任务级汇总，符合隐私计算最小可见原则。

五、集成示例二：WASM 密态载荷

不改平台代码、在 enclave 内执行自定义逻辑的最快路径是 WASM 载荷（WAMR 解释器执行器，默认启用）。

C 载荷编译（需 wasi-sdk-20.0）：

cd /root/teaclave/examples/python/wasm_c_simple_add_payload
make
# 实测：/wasi-sdk-20.0/bin/clang -nostdlib -Wl,--export-all \
#   -Wl,--allow-undefined -Wl,--no-entry -I../../../sdk/payload/wasm/ \
#   -o simple_add.wasm simple_add.c

Rust 载荷编译（固定工具链 + wasm32 目标）：

rustup target add wasm32-unknown-unknown --toolchain nightly-2022-10-22
cd /root/teaclave/examples/python/wasm_rust_psi_payload
RUSTFLAGS= cargo build --target wasm32-unknown-unknown --release
# 实测：Finished release [optimized] target(s) in 1.27s

实测执行结果：wasm_c_simple_add.py 返回 b'7'（3+4 在飞地内完成）；wasm_rust_psi.py 双方各得 6（WASM 载荷内调用密态比较接口完成 PSI）。载荷经任务注册进入 enclave 执行，集成方式与 Python SDK 一致。

六、集成示例三：teaclave_cli 文件加解密管线

既有系统与 Teaclave 数据通道对接时，本地文件先加密为平台认可的格式，任务输出再解密还原：

# 加密（aes-gcm-256：64 位 hex 密钥 + 24 位 hex IV）
teaclave_cli encrypt --algorithm aes-gcm-256 \
  --input-file data.txt \
  --key 0000000000000000000000000000000000000000000000000000000000000002 \
  --iv 012345670123456701234567 \
  --output-file data.enc

# 解密（GCM 认证标签自动校验，密钥错误时报 Aead open_in_place error 并退出 1）
teaclave_cli decrypt --algorithm aes-gcm-256 \
  --input-file data.enc \
  --key 0000000000000000000000000000000000000000000000000000000000000002 \
  --iv 012345670123456701234567 \
  --output-file data.dec

实测往返内容与原文件一致。平台内部任务文件使用 teaclave-file-128 保护文件格式（魔数 ELIF_XGS 实测确认），任务输出的解密方式与密钥背景见《Apache Teaclave 0.6.0 命令与 CLI 详解》第四章。数据源侧集成只需提供 HTTP(S) URL 与密钥（register_input_file 接口），生产环境可对接对象存储。

七、验证清单

构建与集成完成的判据（全部实测通过）：

  1. teaclave_cli --version 输出 teaclave_cli 0.6.0。
  2. make run-unit-tests 输出 192 tested, 192 passed, 0 failed。
  3. make run-functional-tests 54 个功能用例全部 ok（含端到端 echo 与 GBDT 训练）。
  4. builtin_echo.py 返回 b'Hello, Teaclave!'（首个任务闭环）。
  5. PSI 双方各得 3 common items（多方审批链路）。
  6. wasm_c_simple_add.py 返回 b'7'（WASM 执行器）。
  7. teaclave_cli verify 对 enclave_info.toml 校验输出 Verify successfully.（信任链本地校验）。

八、FAQ

Q1：构建时报 undefined reference to EVP_...@OPENSSL_1_1_0？ Ubuntu 22.04 缺 OpenSSL 1.1 兼容库，按 2.3 节自建 1.1.1w 并 ldconfig。

Q2：cargo 报 object not found ... 9ca099ca？ 依赖仓库 incubator-teaclave-crates 的固定提交在并发构建时数据库损坏，重建 cargo git 数据库后重新 fetch（详见安装指南 FAQ）。

Q3：cmake 后构建行为异常（未编测试/未走模拟）？ -cD 选项被首次配置的内部重配置丢弃，务必连续执行两次 cmake 并检查 CMakeCache.txt。

Q4：make run-unit-tests 报 /wasi-sdk-20.0/bin/clang: No such file or directory？ WASM 测试固件需要 wasi-sdk-20.0，从其 GitHub release 下载解压到 /wasi-sdk-20.0。

Q5：示例运行报 _set_npn_protocols 属性不存在？ Python 3.10 + OpenSSL 3 移除了 NPN，按进阶实战文档补 AttributeError 捕获。

Q6：attest 子命令 panic？ 模拟模式边界，远程认证未启用，本地信任校验用 verify 子命令。

九、参考链接

  1. 官方仓库（legacy 分支）：https://github.com/apache/incubator-teaclave/tree/legacy
  2. 官方快速上手文档：https://github.com/apache/incubator-teaclave/blob/legacy/docs/my-first-function.md
  3. Python SDK 与示例：https://github.com/apache/incubator-teaclave/tree/legacy/examples/python
  4. WASM 载荷 SDK：https://github.com/apache/incubator-teaclave/tree/legacy/sdk/payload/wasm
  5. 本文配套文档：《Ubuntu 22.04 安装 Apache Teaclave 指南》《Apache Teaclave 0.6.0 命令与 CLI 详解》《Apache Teaclave 0.6.0 机密计算场景进阶实战详解》