跳转到内容
Etemenanki

安装

本页介绍如何在 Linux 主机上安装两个程序：独立代理 etemenanki-app，以及面板节点 agent katana。你可以下载预编译的 x86_64 二进制文件，也可以从源码构建其中任意一个。完成后，二进制文件位于 /usr/local/bin，/etc 下有一个存放其配置的目录，并且二进制文件能够报告自身版本。

每个程序都是单个可执行文件，没有安装程序，也没有服务单元。两个程序都不在磁盘上保存状态：唯一会创建的文件，是你将某个 etemenanki-app 入站配置为监听 Unix socket 路径时生成的 socket 文件。因此，你只需要创建存放配置的那个目录。

选择构建方式

Section titled “选择构建方式”
etemenanki-app katana
预编译二进制文件 Build CI workflow 的 artifact（x86_64 Linux，glibc） Release 资产 -gnu 和 -musl（x86_64 Linux），各附一个 .sha256 文件
从源码构建 只需要 Etemenanki 仓库 需要 katana 仓库，以及私有 Cargo registry 的读取权限
运行时的 OpenSSL CI 构建链接系统的 libssl.so.3 内置；两个 release 资产都不加载系统 OpenSSL
Hysteria 2 始终编译在内 始终编译在内（Hysteria 2 节点；katana 没有 Hysteria 2 出站）
TUN 入站 始终编译在内 未编译在内；katana 没有 TUN 入站

如果只是想试用，预编译二进制文件是最快的途径。需要其他 CPU 架构、不依赖系统 OpenSSL 的 etemenanki-app，或者某个没有预编译二进制文件的修订版本时，请从源码构建。

支持的平台

Section titled “支持的平台”
程序 操作系统 预编译 说明
etemenanki-app Linux。CI 不为其他操作系统构建。 x86_64 Linux 仅限 Unix：监听器代码无条件使用 Unix socket，因此无法在 Windows 上编译。TUN 入站只在 Linux 上安装 routes；在其他系统上，非空的 routes 列表会报错 tun routes are installed only on Linux; add them with the OS route tool。
katana Linux x86_64 Linux，-gnu 和 -musl release workflow 不构建其他平台或架构。

预编译的 glibc 二进制文件（etemenanki-app，以及 katana -gnu）在 Ubuntu 22.04 上基于 glibc 2.35 编译。glibc 2.35 或更新版本的主机可以运行它们；在更旧的 glibc 上，它们可能无法启动，并报 version `GLIBC_2.xx' not found 错误。katana -musl 二进制文件对 glibc 没有要求。

安装预编译二进制文件

Section titled “安装预编译二进制文件”

etemenanki-app 没有打 tag 的 release。Etemenanki 仓库中的 Build workflow 会在每次推送到 main 时为 x86_64-unknown-linux-gnu 编译 etemenanki-app，每个 pull request 也会触发编译，并将其上传为名为 etemenanki-app 的 workflow artifact。请从 main 上的运行中获取 artifact，不要用 pull request 运行的产物。下载需要该仓库的读取权限。

  1. 打开 main 上最近一次成功的 Build 运行，下载 etemenanki-app artifact。GitHub 会把 artifact 打包成 zip 文件，并且不保留可执行位，所以先解压：

    终端窗口
    unzip etemenanki-app.zip

    使用 GitHub CLI 时，先查找 main 上最近一次成功的 Build 运行，再下载其 artifact。gh run download 会替你解压 zip，但可执行位同样会丢失：

    终端窗口
    RUN_ID=$(gh run list --repo OWNER/Etemenanki --workflow Build --branch main \
      --status success --limit 1 --json databaseId --jq '.[0].databaseId')
    gh run download "$RUN_ID" --repo OWNER/Etemenanki --name etemenanki-app

  2. CI 二进制文件从系统加载 OpenSSL 3（libssl.so.3）。在 Debian 12 和 Ubuntu 22.04 上它属于 libssl3 软件包，在 Debian 13 和 Ubuntu 24.04 上属于 libssl3t64。大多数系统已经安装了它：

    终端窗口
    sudo apt-get install -y libssl3   # Debian 13 和 Ubuntu 24.04 上为 libssl3t64

  3. 安装二进制文件。install -m 0755 会补上 zip 丢失的可执行位：

    终端窗口
    sudo install -m 0755 etemenanki-app /usr/local/bin/etemenanki-app

  4. 确认它能运行：

    终端窗口
    etemenanki-app --version
    etemenanki-app 2.0.0

从源码构建

Section titled “从源码构建”

工具链

Section titled “工具链”

两个程序都使用 Rust 2024 edition，且没有固定工具链版本。请使用通过 rustup 安装的当前 stable Rust。锁定的依赖需要 Rust 1.91 或更新版本（WireGuard 网络栈 smoltcp 0.13 声明了这个最低版本）。编译器过旧时，Cargo 会在编译任何东西之前停止，并报错称已安装的 rustc 不被锁定的软件包支持；列表中包括 smoltcp@0.13.1 requires rustc 1.91。用以下命令更新：

终端窗口
rustup update stable

两个项目都在 release profile 中设置了 lto = true，因此 release 构建需要几分钟时间和相当多的内存。请使用 --locked 构建，让 Cargo 严格使用 Cargo.lock 中的依赖版本，需要改动时直接停止而不是修改它们。

etemenanki-app 仅凭 Etemenanki 仓库即可构建。它的内核 crate（etemenanki-concepts、etemenanki-environment、etemenanki-protocols）是同一 workspace 内的路径依赖，其他所有锁定的依赖都来自 crates.io，因此不需要任何 registry 凭据。

Hysteria 2 和 TUN 入站始终编译在内：app/Cargo.toml 启用了 etemenanki-protocols 的 hysteria 和 tun feature，没有需要额外开启的选项。

所有 TCP 传输层（tls，以及启用 TLS 的 ws 或 grpc）的 TLS 都由 OpenSSL 提供。Hysteria 2 是例外：它的 QUIC 协议栈使用 rustls。你可以链接系统的 OpenSSL（默认方式，也是 CI 的做法），也可以把一份私有的 OpenSSL 编译进二进制文件。

  1. 安装构建依赖。在 Debian 和 Ubuntu 上：

    终端窗口
    # 系统 OpenSSL（默认）
    sudo apt-get install -y build-essential pkg-config libssl-dev
    终端窗口
    # 改用 vendored OpenSSL：不需要 libssl-dev，但 OpenSSL 自身的构建需要 perl 和 make
    sudo apt-get install -y build-essential perl make

    两种方式都需要 C 编译器：一些依赖会编译自带的 C 代码，例如 Hysteria 2 QUIC 协议栈底层的密码学库 ring。

  2. 在 Etemenanki 检出目录的根目录下，构建 etemenanki-app package：

    终端窗口
    # 链接系统的 libssl.so.3
    cargo build --release --locked -p etemenanki-app
    终端窗口
    # 将 OpenSSL 编译进二进制文件
    cargo build --release --locked -p etemenanki-app \
      --features etemenanki-protocols/vendored-openssl

    二进制文件输出到 target/release/etemenanki-app。

  3. 安装：

    终端窗口
    sudo install -m 0755 target/release/etemenanki-app /usr/local/bin/etemenanki-app
    etemenanki-app --version

对于 vendored 构建，ldd /usr/local/bin/etemenanki-app | grep ssl 不会输出任何内容。

确认安装

Section titled “确认安装”

两个程序接受相同的选项：

参数 含义
-V, --version 打印程序名称和版本，然后退出。
-h, --help 打印选项说明，然后退出。
-c, --config <CONFIG> TOML 配置文件的路径。默认：当前目录下的 config.toml。
--test 加载并构建配置，打印配置是否有效，然后退出，不绑定任何监听器。

--version 是检查二进制文件能否在这台主机上运行的最快方法：缺少共享库或 glibc 过旧的问题会在这里暴露出来，此时还不涉及任何配置。版本号是构建该二进制文件时的 crate 版本。

终端窗口
etemenanki-app --version     # etemenanki-app 2.0.0
katana --version             # katana 3.0.1

--version 只显示程序自身 crate 的版本。内核 crate（etemenanki-concepts、etemenanki-environment、etemenanki-protocols）有各自的版本，内核发布并不总会提升 etemenanki-app 的版本。从当前 release 构建的 etemenanki-app 仍然报告 2.0.0，但其中包含的是 etemenanki-protocols 2.0.2。katana 3.0.1 基于 etemenanki-protocols 2.0.1 构建。两者的区别仅在于 SOCKS 如何处理 UDP 关联。这项改动大部分位于 SOCKS 入站，而 katana 没有 SOCKS 入站。其余部分让 SOCKS 客户端的双栈 UDP socket 能够收到 IPv4 中继的回复；katana 的 socks 出站会按中继自身的地址族绑定 UDP socket，因此不需要这项改动。要查看某次源码构建包含哪些内核版本，请在构建所用 checkout 的 Cargo.lock 中查找。

有了配置之后，下一步检查是 --test。文件有效时，etemenanki-app 打印 Configuration OK.，katana 打印 Configuration OK。下一页第一个代理会编写一份配置并对其进行测试。

建议的文件布局

Section titled “建议的文件布局”

两个程序都没有内置的文件存放位置。etemenanki-app 和 katana 从 -c 读取配置，其他所有文件（证书、CA 证书包、geodata、katana 的审计规则列表）都从你在配置中写下的路径读取。下面的布局把每个程序的文件放在 /etc 下的一个目录中：

  • 文件夹usr/local/bin/
    • etemenanki-app
    • katana
  • 文件夹etc/
    • 文件夹etemenanki/
      • config.toml 通过 -c 传入的文件
      • 文件夹certs/
        • fullchain.pem TLS 入站使用的证书链
        • privkey.pem 私钥，仅服务可读
      • geoip.dat 仅当规则使用 geoip 时需要
      • geosite.dat 仅当规则使用 geosite 时需要
    • 文件夹katana/
      • config.toml
      • 文件夹certs/
        • fullchain.pem
        • privkey.pem
      • geoip.dat
      • geosite.dat
      • rules.txt 本地审计规则，设置了 rule_list_path 时使用

关于这些文件的几点说明：

  • 私钥。 让私钥只对服务所用的用户可读，例如 sudo install -m 0600 privkey.pem /etc/etemenanki/certs/；如果服务不以 root 运行，还要修改文件所有者。
  • Geodata。 两个程序都读取 v2ray 格式的 geoip.dat 和 geosite.dat 文件。v2fly 项目发布了这些文件：geoip.dat，以及 dlc.dat（保存为 geosite.dat）。只有当某条规则使用 geoip 或 geosite 匹配条件时才需要它们；使用了这类匹配条件却没有配置对应文件的规则属于配置错误。
  • 热重载。 两个程序都会监视配置文件所在的目录。etemenanki-app 只在配置文件本身的字节发生变化时才重载，因此单独替换证书不会触发重载。参见热重载。

故障排查

Section titled “故障排查”
现象 原因 解决方法
error while loading shared libraries: libssl.so.3: cannot open shared object file etemenanki-app 的 CI 二进制文件或默认的源码构建需要系统的 OpenSSL 3。 安装 libssl3（Debian 13 和 Ubuntu 24.04 上为 libssl3t64），或使用 --features etemenanki-protocols/vendored-openssl 构建。
version `GLIBC_2.xx' not found 主机的 glibc 比构建二进制文件时使用的版本更旧。 katana 请使用 -musl 资产。etemenanki-app 请在该主机上从源码构建。
sha256sum: katana-…: No such file or directory 校验前二进制文件已被重命名，或保存在了其他目录。 保留原始文件名，并在同时存放两个文件的目录中运行 sha256sum -c。
Cargo 停止并报 smoltcp@0.13.1 requires rustc 1.91 Rust 工具链对于锁定的依赖来说过旧。 rustup update stable。
Could not find openssl via pkg-config 或 Could not find directory of OpenSSL installation 默认的 etemenanki-app 构建找不到 OpenSSL 开发文件。 安装 pkg-config 和 libssl-dev，或使用 vendored OpenSSL feature 构建。
katana 的构建在 Cargo 连接私有 registry 时失败 Cargo 没有该私有 registry 的 token，或 token 没有访问权限。 按从源码构建中的说明设置 token。
configuration invalid: No such file or directory (os error 2)，或 katana 报出同样内容的 configuration error: … 配置中的相对路径从另一个工作目录打开。 使用绝对路径。
使用 vendored OpenSSL 时，TLS 出站或 DNS over TLS、HTTPS 证书验证失败 vendored OpenSSL 在 /usr/local/ssl 中查找根证书。 设置 SSL_CERT_FILE，或设置 ca_file。

后续步骤

Section titled “后续步骤”

安装好二进制文件后，编写一份配置并运行它。以服务方式运行程序（包括使用低端口和 TUN 所需的权限）的内容见运行。katana 的配置和面板设置在本指南的 katana 部分中介绍。

第一个代理编写一份最小的 etemenanki-app 配置，用 --test 检查它，并让流量经过它。
运行以服务方式运行程序、重载配置并升级二进制文件。
配置文件etemenanki-app 如何读取它的 TOML 文件，以及哪些内容会被拒绝。
热重载编辑正在运行的 etemenanki-app 的配置时，会发生哪些变化。