企业官网建设流程全解析

Ente CLI 实战指南：端到端加密云数据的命令行导出与解密

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

Ente 是一个以端到端加密为核心的开源云平台，覆盖照片、认证器（Auth）等多种数据。Ente CLI是官方提供的命令行工具，主要用于将你在 Ente 中的数据（照片/视频、认证器条目）批量导出到本地，并附带一些实用能力，例如解密 Ente Auth 的加密导出文件。本文以 cli/README.md 为骨架，结合仓库内 cli/main.go、cli/pkg/account.go、cli/pkg/sync.go 等源码，系统讲解 Ente CLI 的安装、账户管理、导出、解密与 Docker 部署全流程。读完本文，你将掌握：如何在一台全新机器上安装并登录 Ente CLI、如何为一个或多个账户配置导出目录并启动同步、如何利用过滤器精确控制导出范围、如何解密 Auth 导出文件，以及如何通过配置文件和 Docker 适配自托管环境。

一、Ente CLI 是什么

从 cli/README.md 的定位描述看，Ente CLI 是一个Command Line Utility，核心用途是从 Ente 导出数据；除此之外它还支持解密 Ente Auth 的导出。仓库中 cli/cmd/root.go 将根命令描述为 "CLI tool for exporting your photos from Ente"，而从实际子命令（account、export、auth decrypt、admin、version）可以看出，它实际上覆盖了照片与认证器两大类数据的管理与导出：

从 cli/main.go 可以看到当前仓库中版本号为v0.3.0（var AppVersion = "v0.3.0"），运行时可通过ente version输出。CLI 基于 Go 实现，命令框架使用 cobra，配置读取使用 viper，本地状态存储使用 bbolt 数据库。

二、安装 Ente CLI

2.1 方式一：下载预编译二进制（推荐）

README 推荐的方式是从官方 GitHub Releases 下载预编译二进制，注意过滤以cli-v0为前缀的 tag 对应的版本（例如cli-v0.3.0）。下载后得到的是独立、静态链接的二进制，无任何外部依赖，可直接运行，或放入PATH中的任意目录（例如/usr/local/bin）。

2.2 方式二：一键构建全部平台二进制

仓库提供了 cli/release.sh 脚本，可交叉编译出所有目标平台的二进制并输出到bin/目录：

./release.sh

从脚本源码看，它通过git describe --tags自动获取最新的cli-*标签并作为版本号（VERSION=${LATEST_TAG#cli-}），随后在CGO_ENABLED=0环境下按平台矩阵构建：

• Windows：386、amd64（产物为.exe）；
• Linux：386、amd64、arm、arm64；
• macOS（darwin）：amd64、arm64。

构建时使用-ldflags="-X main.AppVersion=${VERSION} -s -w" -trimpath注入版本号并精简二进制，最终产物为bin/ente-<os>-<arch>（或.exe）。

2.3 方式三：从源码构建

如果你只想要当前机器平台的单个二进制，直接使用 Go 构建：

go build -o "bin/ente" main.go

这里main.go是 CLI 的入口（见 cli/main.go），它会完成配置初始化、密钥装载、数据库打开等工作。两种方式产出的都是 standalone、无动态依赖的静态二进制。

2.4 方式四：Docker 容器

如果你倾向容器化运行，可以使用仓库根目录下的 cli/docker-compose.yml 与 cli/Dockerfile，详见后文「七、使用 Docker 运行」。

三、快速上手：查看帮助与版本

安装完成后，先运行帮助命令查看所有可用命令：

ente --help

根命令支持-h/--help与-t/--toggle两个全局 flag（后者为 cobra 脚手架自带的占位 flag，见 cli/cmd/root.go）。查看版本：

ente version

从 cli/main.go 源码可见，如果你通过配置文件把 API 端点指向了非官方地址，ente version还会额外打印一行Custom endpoint: <你的端点>，方便确认当前连接的是自托管服务。

3.1 首次运行的初始化行为

从 cli/main.go 可以了解 CLI 的启动流程：

• version、docs、help三个命令不需要初始化，其余命令都会初始化密钥与数据库；
• 配置目录优先读取环境变量ENTE_CLI_CONFIG_DIR（兼容旧的ENTE_CLI_CONFIG_PATH），为空时默认使用~/.ente（代码中为homeDir + "/.ente"）；
• 数据库文件为配置目录下的ente-cli.db，是一个 bbolt 数据库（cli/pkg/cli.go 中Init()会创建accountsbucket 与临时下载目录）；
• CLI 会在系统密钥链（keychain/secret service）中创建/读取一个DeviceKey（32 字节），用于在本地加密账户密钥（见 cli/pkg/secrets/key_holder.go）。这是本地安全的关键：磁盘上不落明文密钥。

四、账户管理

Ente CLI 支持同时配置多个账户（例如你自己和家人的账户），并为每个账户单独设置导出目录。

4.1 添加账户：ente account add

ente account add

[!NOTE]ente account add不会创建新账户，它只是把已存在的 Ente 账户加入 CLI 的账户列表，以便后续导出使用。创建新账户请使用 Ente 的移动端、Web 或桌面应用（cli/cmd/account.go 中add的 Long 描述也明确说明了这一点）。

执行后 CLI 会以交互方式引导你完成登录（见 cli/pkg/account.go 的AddAccount流程）：

1. 选择应用类型：photos或auth（默认photos，由 cli/internal/promt.go 的GetAppType交互收集）；
2. 输入导出目录（GetExportDir会校验目录存在且可写，支持~展开，见 cli/internal/promt.go）；
3. 输入邮箱地址；
4. 登录认证：CLI 会根据账户情况自动走以下一种或多种方式（见 cli/internal/api/login.go 与 cli/pkg/account.go）：
   • SRP 密码认证：调用/users/srp/attributes、/users/srp/create-session、/users/srp/verify-session完成安全远程口令协议认证；
   • 邮箱 OTP 验证：如果账户未设置密码或启用了邮箱 MFA，会通过/users/ott发送一次性验证码，再调用/users/verify-email校验；
   • TOTP 二次验证：若响应标记需要 MFA，调用/users/two-factor/verify；
   • Passkey 验证：若需要，调用/users/two-factor/passkeys/get-token。

认证成功后，CLI 解密账户的密钥信息（MasterKey、SecretKey、Token 等），并以DeviceKey 加密后存入 bbolt 数据库（见 cli/pkg/account.go 的storeAccount，使用model.MakeEncString对密钥做本地加密存储）。成功后输出提示：

Account added successfully run `ente export` to initiate export of your account data

4.2 列出账户：ente account list

ente account list

ListAccounts（见 cli/pkg/account.go）会打印已配置的账户数量，以及每个账户的 Email、ID、App 类型、ExportDir，格式如下：

Configured accounts: 1 ==================================== Email: user@example.com ID: 12345 App: photos ExportDir: /home/user/ente-export ====================================

4.3 修改导出目录：ente account update

ente account update --app auth/photos --email email@domain.com --dir ~/photos

参数说明（见 cli/cmd/account.go 的 flag 定义）：

需要注意：update只支持photos、locker、auth三种 app 取值（cli/cmd/account.go）；locker类型的账户可以被配置，但当前版本的导出流程会跳过 Locker 数据（见 cli/pkg/sync.go：Locker export is not supported）。UpdateAccount在写入前会调用ValidateDirForWrite校验目标目录存在且可写（cli/pkg/account.go）。

4.4 获取 Token：ente account get-token

ente account get-token --app photos --email email@domain.com

该命令从本地密钥库解密并打印指定账户在指定应用下的访问 Token（见 cli/pkg/account.go），可用于排查登录问题或集成其他工具。

五、导出数据

5.1 启动导出：ente export

ente export

执行export后，CLI 会遍历所有已配置账户（见 cli/pkg/sync.go 的Export流程）：

1. 若没有任何账户，提示先使用account add；
2. 依次处理每个账户：日志以[app-email]为前缀（例如[photos-user@example.com]）；
3. 跳过未配置导出目录、导出目录校验失败、被--emails过滤器排除的账户；
4. Locker 账户直接跳过（当前版本不支持 Locker 导出）；
5. auth类型的账户走 Auth 导出逻辑（输出ente_auth.txt，见后文 5.4）；
6. photos类型的账户走完整同步流程：拉取远端相册元数据 → 拉取文件元数据 → 创建本地目录 → 下载并解密文件；
7. 网络错误时自动重试：最多重试 20 次，每次等待时间按retryCount * 10秒递增（cli/pkg/sync.go）。

5.2 导出过滤器

ente export支持以下 flags（定义见 cli/cmd/export.go，完整帮助见 cli/docs/generated/ente_export.md）：

过滤器逻辑实现在 cli/pkg/model/filter.go：

• SkipAccount：仅当--emails非空时生效，邮箱匹配不区分大小写并忽略首尾空格；
• SkipAlbum：依次判断——相册名是否被排除（ExcludeAlbums/Albums）、是否共享（ExcludeShared）、是否隐藏（ExcludeHidden）；
• excludeByName：排除列表优先于包含列表，且匹配同样忽略大小写与首尾空格。

这些边界行为都有对应的单元测试（见 cli/pkg/model/filter_test.go），例如"排除列表优先级高于包含列表""包含列表下不在列表中的相册被跳过"等用例，可作为精确控制导出范围的依据。

5.3 同步流程与本地状态

photos 账户的同步核心在 cli/pkg/sync.go 的SyncAccount与 cli/pkg/remote_sync.go：

1. LoadSecrets用 DeviceKey 解密账户的 Token/MasterKey/SecretKey（cli/pkg/secrets/key_holder.go）；
2. fetchRemoteCollections：按增量时间戳拉取远端相册并解密相册密钥（自己的相册用 MasterKey 解密，共享相册用 PublicKey/SecretKey 做 sealed box 解密，见 cli/pkg/secrets/key_holder.go）；
3. fetchRemoteFiles：对每个相册增量拉取文件元数据，写入本地 bbolt 缓存；
4. createLocalFolderForRemoteAlbums：在导出目录创建对应的相册文件夹；
5. syncFiles：下载文件并本地解密。

下载与解密逻辑在 cli/pkg/download.go：文件先下载到临时目录（默认系统 temp，可通过环境变量ENTE_CLI_TMP_PATH覆盖，见 cli/pkg/cli.go），再使用文件的密钥 + nonce 解密为.decrypted文件，随后删除密文。Live Photo 的 zip 包还会被解包拆分为 image 与 video 两部分（UnpackLive，cli/pkg/download.go）。同步断点通过每相册的最后同步时间存储于本地数据库，因此重复运行ente export只会增量同步新增/变更内容，不会重复下载。

5.4 Auth 账户的导出

auth类型的账户执行的是SyncAuthAccount（见 cli/pkg/sync_authenticator.go）：

• 通过/authenticator/entity/diff增量拉取认证器条目（每次 500 条，自动翻页，见 cli/internal/api/authenticator.go）；
• 通过/authenticator/key获取认证器主密钥并用账户 MasterKey 解密（cli/pkg/secrets/key_holder.go）；
• 逐条解密条目（ChaCha20-Poly1305 + Base64，见 cli/pkg/mapper/authenticator.go）；
• 最终把条目明文逐行写入导出目录下的ente_auth.txt（cli/pkg/sync_authenticator.go）。

如果ente_auth.txt已存在，CLI 会先将其重命名为带时间戳的备份文件（如ente_auth_2026-09-09_04-30-00.txt），再写入新文件，避免覆盖丢失。

六、解密 Ente Auth 的导出文件

ente auth decrypt用于解密从 Ente Auth 导出的加密 JSON 文件：

ente auth decrypt [input] [output] [flags]

Flags：

底层实现在 cli/pkg/authenticator/decrypt.go，流程如下：

1. 解析输入 JSON，格式包含version、kdfParams（memLimit/opsLimit/salt）、encryptedData、encryptionNonce字段；
2. 仅支持version == 1的导出格式，否则报错unsupported export version；
3. 未提供-p时，通过终端无回显方式收集密码（cli/internal/promt.go 的GetSensitiveField）；
4. 使用Argon2idKDF 从密码派生密钥：argon2.IDKey(password, salt, opsLimit, memLimit/1024, 1, 32)（见 cli/internal/crypto/crypto.go），memLimit必须 ≥ 1024、opsLimit必须 ≥ 1；
5. 使用派生密钥 + nonce 对密文做 ChaCha20-Poly1305 认证解密（DecryptChaChaBase64Auth）；
6. 密码错误时会提示 "Please check your password and try again"；成功后明文写入输出文件并打印解密路径。

七、使用 Docker 运行

7.1 配置与启动

仓库提供 cli/docker-compose.yml，核心要点如下：

• cli-data卷是必须的：需要把宿主机目录挂载到容器内的/cli-data（代码中 cli/utils/constants/constants.go 定义了CliDataPath = "/cli-data/"），CLI 会把数据库、密钥等状态数据存放到这里；
• 可以额外挂载导出目录到/data（或其他路径），这样在容器内添加账户时把导出目录填/data即可；
• 容器内固定执行/bin/sh并开启stdin_open: true与tty: true，以便交互式执行 CLI 命令。

启动构建（detached 模式）：

docker-compose up -d --build

[!NOTE] 构建该镜像需要 BuildKit。如果遇到相关报错，一个快速的解决办法是在构建命令前加上DOCKER_BUILDKIT=1。

7.2 进入容器执行命令

docker-compose exec ente-cli /bin/sh -c "./ente-cli version" docker-compose exec ente-cli /bin/sh -c "./ente-cli account add"

从 cli/Dockerfile 可以看到镜像采用两阶段构建：先用golang镜像在CGO_ENABLED=0环境下编译出ente-cli二进制，再复制到精简的alpine基础镜像中运行。在容器模式下，cli/main.go 会把配置目录强制切换到/cli-data，若未挂载卷会直接报错提示Please mount a volume to /cli-data。

八、配置文件与自托管端点

8.1 配置文件位置

CLI 使用 viper 读取 YAML 配置（见 cli/main.go 与 cli/config.yaml.example），配置文件可以放在以下任一位置：

• $HOME/.ente/config.yaml
• 当前工作目录下的config.yaml
• $ENTE_CLI_CONFIG_DIR/config.yaml

8.2 配置项

cli/config.yaml.example 展示了两个配置项：

endpoint: api: "http://localhost:8080" log: http: false # log status code & time taken by requests

[!IMPORTANT] 默认端点指向 Ente 官方服务。如果你运行的是自托管 Ente 服务器，必须把endpoint.api改为自己的服务地址（例如http://localhost:8080），CLI 才能连上你的实例。使用自托管端点时，ente version会提示Custom endpoint。

此外还支持以下环境变量：

九、CLI 文档与命令参考

仓库在 cli/docs/generated 目录下存放了所有命令的 Markdown 文档（由 cobra 自动生成），包括：

• ente.md：根命令与子命令总览；
• ente_account.md 及ente_account_add/list/update/get-token系列；
• ente_export.md：导出命令完整 flag 参考；
• ente_auth_decrypt.md：解密命令参考；
• ente_admin_*系列：管理员命令参考。

如果修改了命令定义，需要重新生成文档，可执行（见 cli/main.go 与 cli/cmd/root.go）：

go run main.go docs

该命令会把文档重新生成到./docs/generated目录。需要查看某个命令的完整参数时，也可以随时使用ente <command> --help。

十、常见使用场景速查

场景一：导出自己的全部照片/视频

ente account add # 按提示选择 photos、输入导出目录与邮箱完成登录 ente export

场景二：只导出某个相册，排除共享相册

ente export --albums "2026旅行" --shared=false

场景三：为多个家人账户分别导出到不同目录

ente account add ente account update --app photos --email family@example.com --dir ~/ente/family ente export

场景四：解密 Auth 导出文件

ente auth decrypt ente_auth_export.json ente_auth_export.txt -p "你的密码"

场景五：对接自托管 Ente 服务器

在~/.ente/config.yaml中写入：

endpoint: api: "https://photos.your-server.com"

然后正常ente account add、ente export即可。

十一、总结

Ente CLI 以"数据可随时带走的自主权"为设计目标：通过 SRP / OTP / TOTP / Passkey 等完整登录流程接入账户，将密钥以 DeviceKey 加密后存放在本地 bbolt 数据库中，导出时先增量同步元数据再下载解密文件，整个过程密钥不出本地，因此导出的内容可以直接脱离 Ente 生态独立使用。无论是官方服务用户还是自托管用户，掌握account、export、auth decrypt三组命令，配合过滤器与 Docker 部署方式，就能搭建一套可靠的 Ente 数据备份与迁移流水线。更多命令细节，可继续翻阅 cli/docs/generated/ente.md 与 cli/README.md。

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente