Ubuntu 22.04 安装 Apache Teaclave 指南

目标：在 Ubuntu 22.04 上完成 Apache Teaclave 0.6.0 的 SGX 模拟模式源码构建，单元测试 192 项、功能测试 54 项与 CLI 加解密全部实测通过。

Apache Teaclave 是 ASF 顶级项目旗下的机密计算（TEE）生态：主仓库当前为子项目入口（Teaclave SGX SDK、TrustZone SDK、Java TEE SDK 等），原 Teaclave FaaS 平台位于 legacy 分支（最后发布版 v0.6.0）。本文在无 SGX 硬件的 Ubuntu 22.04 服务器上，使用官方模拟模式（SGX_MODE=SW）完整构建并验证该平台，所有命令与回显均为实测记录。

一、环境信息

本文所有命令与回显均在以下环境实测：

💡 技术拓展：机密计算（Confidential Computing）硬件路线对比——Intel SGX 提供应用级飞地（内存加密、页粒度隔离，适合进程级密态计算）；Arm TrustZone 提供安全/非安全双世界（整机分区隔离，适合富设备与 IoT）；AMD SEV 提供虚拟机级内存加密（适合云上多租户）。Teaclave FaaS 平台基于 Intel SGX 构建，Teaclave 生态另有 TrustZone SDK 覆盖 Arm 路线。本文采用 SGX 模拟模式，无需任何 TEE 硬件即可完成全部软件链路验证。

二、前置条件

1. Ubuntu 22.04 x86_64 服务器，root 权限，磁盘剩余空间不低于 60 GB。
2. 内存不低于 16 GB（12 路并行编译峰值实测占用约 10 GB）。
3. 可访问 GitHub、download.01.org（Intel SGX 下载站）与 static.rust-lang.org；内网环境可为 shell 配置代理（本文实测经代理完成全部下载）。
4. 无需 SGX 硬件与 BIOS 支持：模拟模式在普通 CPU 上完成全部构建与测试。

三、版本选型说明

💡 技术拓展：Teaclave 平台（FaaS）与 Teaclave SGX SDK 是两类交付物——前者是带任务调度、多方审批、内置函数库的完整平台（本文对象）；后者是构建自定义 TEE 应用的开发框架（活跃子项目，最新 tag v1.1.6）。选型时若只需要 SGX 应用开发框架，直接用 SGX SDK；若要学习/复用完整任务编排与隐私计算函数体系，用本文的 legacy 平台。

本文构建 legacy 分支 HEAD（65886ec）：包含 v0.6.0 全部代码及最后一批文档修正，且实测可完整构建。

四、方案 A：完整平台源码构建（SGX 模拟模式）

4.1 安装系统依赖

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

实测版本：cmake 3.22.1、gcc-9 9.5.0、protoc 3.12.4。依赖项的实测理由：

4.2 安装 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

安装器两个交互项实测依次输入：no（不安装 PSW，模拟模式不需要）、/opt（安装前缀）。安装完成后验证：

ls /opt/sgxsdk/lib64 | grep -c sim

实测输出 8，模拟库（libsgx_urts_sim.so、libsgx_trts_sim.a、libsgx_epid_sim.so 等）齐全。SDK 的 ubuntu20.04 包在 22.04 上可直接使用，但要注意 4.3 节的 OpenSSL 兼容问题。

4.3 构建 OpenSSL 1.1.1 兼容层

SGX SDK 2.17.1 的模拟库依赖 OpenSSL 1.1 的版本化符号，Ubuntu 22.04 仅提供 3.0。实测症状——链接服务时报：

/opt/sgxsdk/lib64/libsgx_urts_sim.so: undefined reference to `EVP_sha1@OPENSSL_1_1_0'
/opt/sgxsdk/lib64/libsgx_uae_service_sim.so: undefined reference to `EVP_PKEY_CTX_new@OPENSSL_1_1_0'

源码构建 OpenSSL 1.1.1w 并注册动态链接器：

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
ldconfig -p | grep libcrypto.so.1.1

实测 ldconfig -p 能查询到 libcrypto.so.1.1 与 libssl.so.1.1 后，链接错误消失。

4.4 安装固定 Rust 工具链

Teaclave 的 CMake 构建系统强制指定 nightly-2022-10-22 工具链：

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
rustc --version

实测输出：

rustc 1.66.0-nightly (5c8bff74b 2022-10-21)

4.5 获取源码与子模块

cd /root
git clone --depth 1 --branch legacy https://github.com/apache/incubator-teaclave.git teaclave
cd teaclave
git log -1 --format="%H %ad" --date=iso
git submodule update --init --recursive

实测输出：

65886ec4bb980f6f0a8a1c025478df570cd11b59 2025-07-17 +0000
Submodule 'third_party/rust-sgx-sdk' (https://github.com/apache/incubator-teaclave-sgx-sdk.git) registered for path 'third_party/rust-sgx-sdk'
Submodule 'third_party/wasm-micro-runtime' (https://github.com/bytecodealliance/wasm-micro-runtime.git) registered for path 'third_party/wasm-micro-runtime'
Submodule 'third_party/mesapy' (https://github.com/ssl-hep/mesapy.git) registered for path 'third_party/mesapy'

三个子模块分别固定在 rust-sgx-sdk ec44320、wasm-micro-runtime d856af6 与 mesapy 对应版本。

4.6 串行预取 cargo 依赖

并行构建时多个 cargo 进程会争抢同一 git 依赖数据库，实测在代理网络下引发部分拉取损坏（object not found - no match for id 9ca099ca...，涉及 tonic/casbin/rustface 等来自 incubator-teaclave-crates 的依赖）。先串行预取，再以离线方式构建：

source /opt/sgxsdk/environment
cd /root/teaclave
mkdir -p build && cd build
make prep
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

实测三次 fetch 均正常退出。若 fetch 仍报 object not found，说明 cargo git 数据库已在此前并发构建中损坏，手动重建：

rm -rf /root/.cargo/git/db/incubator-teaclave-crates-* /root/.cargo/git/checkouts
mkdir -p /root/.cargo/git/db /root/.cargo/git/checkouts
git clone --bare https://github.com/apache/incubator-teaclave-crates \
  /root/.cargo/git/db/incubator-teaclave-crates-c8106113f74feefc
git -C /root/.cargo/git/db/incubator-teaclave-crates-c8106113f74feefc \
  cat-file -e 9ca099caa1508c3b7ab1a54899f390f9232f10ff && echo DB_OBJ_OK

实测输出 DB_OBJ_OK 后重新执行上方三条 cargo fetch 即恢复。

4.7 CMake 配置（必须执行两次）

首次配置会因子模块初始化触发内部重配置，实测 -D 选项在重配置中被丢弃回落为默认值（日志出现 Configure will be re-run and you may have to reset some variables.，随后 SGX_MODE 由 SW 变回 HW）。因此连续执行两次，第二次检查缓存：

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

实测第二次配置后缓存：

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

同时确认配置汇总为 SGX_MODE=SW。三项参数：SGX_SIM_MODE=ON 启用模拟模式；TEST_MODE=ON 编译测试与固件（运行测试必需）；OFFLINE=ON 使用 4.6 节预取的依赖（规避并行网络竞态）。

4.8 全量构建

make -j12

实测干净全量构建（601 个 crate、全部服务 enclave、WAMR、测试目标）在本机（12 核，cargo 依赖缓存已按 4.6 节预热）从零计时耗时 487 秒，约 8 分钟，退出码 0；冷缓存首次构建需另计依赖下载时间。构建完成后产物结构：

release/
├── bin/teaclave_execution_service_libos       # LibOS 执行器
├── cli/teaclave_cli                           # 命令行工具（实测 --version 输出 0.6.0）
├── examples/                                  # 示例配置与材料
├── lib/                                       # 依赖库
├── services/                                  # 7 个服务二进制 + signed enclave + enclave_info.toml + 审计者材料
├── tests/                                     # 单元/功能/集成测试 enclave + 测试固件
└── tools/teaclave_sgx_tool                    # enclave 信息工具

五、方案 B：仅构建 teaclave_cli

只需要文件加解密工具时，可跳过全量构建，在完成 4.1–4.7 后执行：

cd /root/teaclave/build
make teaclave_cli

实测退出码 0，产物 release/cli/teaclave_cli（约 109 MB，debug 构建）。该路径不编译 enclave 与服务，几分钟内完成，适合快速获得平台认可格式的加解密工具（aes-gcm-128/256 与 teaclave-file-128）。

六、方案对比

无 SGX 硬件时两者均使用模拟模式；如需真实远程认证与内存加密，需 SGX 硬件服务器并改用默认 HW 模式构建（流程一致，去掉 SGX_SIM_MODE 参数），本文未做硬件验证。

七、基础配置

7.1 构建环境变量（写入 shell profile 建议）

source /opt/sgxsdk/environment          # 导出 SGX_SDK 与模拟模式库路径
export TEACLAVE_PROJECT_ROOT=/root/teaclave
export SGX_MODE=SW
export RUST_LOG=info

7.2 服务运行环境变量

启动服务前设置（模拟模式实测值）：

7.3 运行时配置文件

服务读取 release/services/runtime.config.toml（构建时由 config/runtime.config.toml 生成），定义服务地址、认证策略与审计者列表；测试场景无需修改，生产部署需按网络拓扑调整地址与密钥材料。

八、验证清单

全部实测通过的验证步骤：

1. 工具链核对：rustc --version 输出 1.66.0-nightly（5c8bff74b 2022-10-21）；protoc --version 输出 libprotoc 3.12.4。
2. 模拟库核对：ls /opt/sgxsdk/lib64 | grep -c sim 输出 8。
3. 配置核对：grep SGX_SIM_MODE /root/teaclave/build/CMakeCache.txt 输出 SGX_SIM_MODE:BOOL=ON。
4. 单元测试：make run-unit-tests，实测汇总 192 tested, 192 passed, 0 failed（需先安装 wasi-sdk-20.0 到 /wasi-sdk-20.0，供 WASM 测试固件编译；从其 GitHub release 下载解压即可）。
5. 功能测试：make run-functional-tests，实测自动拉起全部服务，54 个用例全部 ok（覆盖六个服务接口与端到端 echo、GBDT 训练、多方任务），退出码 0。
6. CLI 功能：teaclave_cli encrypt（aes-gcm-256）后 decrypt 还原，实测内容与原文件一致；错误密钥解密实测报 Error: Aead open_in_place error 并退出码 1。
7. 信任链校验：teaclave_cli verify 对 release/services/enclave_info.toml 用三名审计者公钥校验，实测输出 Verify successfully.。
8. 端到端示例：启动七服务后运行 examples/python/builtin_echo.py "Hello, Teaclave!"，实测返回 b'Hello, Teaclave!'（Python 3.10 需为 sdk/python/teaclave.py 补充 NPN 兼容捕获，见 FAQ）。

九、FAQ

Q1：CMake 配置末尾报 cannot create target "sgxapp-NOTFOUND"？ Ubuntu 22.04 无 python 命令（仅 python3），CMake 调用解析脚本静默失败。安装 python-is-python3 后删除 build 目录重新配置。

Q2：链接时报大量 undefined reference to ...@OPENSSL_1_1_0？ SGX SDK 模拟库需要 OpenSSL 1.1，按 4.3 节自建兼容层。

Q3：构建中 rust-sgx-sdk 的 sgx_sm2.cpp 报 ordered comparison of pointer with integer zero？ GCC 11 的语言规则收紧，安装 gcc-9 并在 cmake 时指定 -DCMAKE_C_COMPILER=gcc-9 -DCMAKE_CXX_COMPILER=g++-9。

Q4：构建中报 Could not find protoc？ 安装 protobuf-compiler。

Q5：cargo fetch / make 报 object not found - no match for id (9ca099ca...)？ cargo git 数据库并发竞态损坏（依赖仓库 incubator-teaclave-crates 已更名 teaclave-crates，旧提交仍在 legacy 分支可达）。按 4.6 节手动重建数据库后重新 fetch，并坚持先预取后 OFFLINE 构建。

Q6：cmake 两次执行后 SGX_MODE 仍是 HW？ 第二次执行时未带齐 -D 参数或未检查缓存。以 4.7 节原样命令执行两次，并确认 grep SGX_SIM_MODE CMakeCache.txt 为 ON。

Q7：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-linux.tar.gz，约 80 MB）解压至根目录形成 /wasi-sdk-20.0。

Q8：运行 Python 示例报 'SSLContext' object has no attribute '_set_npn_protocols'？ Python 3.10 + OpenSSL 3 移除了 NPN 接口。将 sdk/python/teaclave.py 中 except NotImplementedError: 改为 except (NotImplementedError, AttributeError):（SDK 已有 ALPN 回退，实测不影响连接）。

Q9：attest 子命令 panic（index out of bounds, attestation/src/report.rs:526）？ 模拟模式认证报告链路未启用的预期行为，本地信任校验改用 verify 子命令。

十、卸载与清理

cd /root/teaclave/build
make -j12 clean                                    # 清理编译产物（可选）
rm -rf /root/teaclave/build /root/teaclave/release # 构建目录与产物
rm -rf /root/teaclave                              # 源码
rm -rf /opt/sgxsdk                                 # SGX SDK
rm -rf /opt/openssl-1.1 /etc/ld.so.conf.d/openssl-1.1.conf && ldconfig   # OpenSSL 兼容层
rm -rf /wasi-sdk-20.0                              # WASM 工具链（如安装）
rustup toolchain uninstall nightly-2022-10-22      # 固定工具链
rm -rf /root/.cargo /root/.rustup                  # 彻底移除 rustup（影响其他项目时慎用）

保留环境仅清理缓存时，删除 build 目录与 /root/.cargo/registry、/root/.cargo/git 即可，下次构建重新预取。

十一、参考链接

1. Apache Teaclave 官网：https://teaclave.apache.org/
2. 平台源码（legacy 分支）：https://github.com/apache/incubator-teaclave/tree/legacy
3. v0.6.0 发布说明：https://github.com/apache/incubator-teaclave/releases/tag/v0.6.0
4. 构建系统文档：https://github.com/apache/incubator-teaclave/blob/legacy/docs/build-system.md
5. Intel SGX SDK 2.17.1：https://download.01.org/intel-sgx/sgx-linux/2.17.1/distro/
6. wasi-sdk-20.0：https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-20
7. OpenSSL 1.1.1w：https://github.com/openssl/openssl/releases/tag/OpenSSL_1_1_1w
8. 本文配套文档：《CentOS 8 安装 Apache Teaclave 指南》《Apache Teaclave 0.6.0 快速入门与集成示例》《Apache Teaclave 0.6.0 命令与 CLI 详解》《Apache Teaclave 0.6.0 机密计算场景进阶实战详解》