Ente CLI 完整指南：用命令行实现照片库导出、增量备份与 NAS 定时同步

Ente CLI 完整指南：用命令行实现照片库导出、增量备份与 NAS 定时同步

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

本指南以 Ente 官方文档 CLI (Command Line Interface) 为骨架，结合仓库内 cli 模块的 Go 源码（命令定义、导出过滤器、磁盘同步逻辑）与自动生成命令文档，系统讲解 Ente CLI 的安装、账号管理、增量导出、cron 自动化、NAS 单向同步以及底层工作原理。读完本文，你将能够在一台无图形界面的服务器或 NAS 上，用纯命令行工具把 Ente Photos 的整个图库（含相册结构与元数据）安全地备份到本地，并按计划自动增量同步。

CLI 是什么？为什么值得用？

Ente CLI 是面向进阶用户提供的命令行工具，为 Ente Photos 提供程序化访问能力。官方文档将其定位为“advanced users 的工具”，核心能力包括：

• 将整个图库或指定相册导出到本地存储；
• 通过 cron 等计划任务实现自动化导出；
• 将数据同步到 NAS 或其他存储系统；
• 以脚本方式执行批量操作。

CLI 特别适合以下场景：

• 定期自动化备份：把照片备份到本地或 NAS，无需打开 GUI；
• 服务器到服务器传输：无图形界面的 headless 环境；
• 偏好命令行的进阶用户；
• 定时任务：借助 cron（Linux/macOS）或任务计划程序（Windows）调度；
• 脚本化与自动化工作流。

从源码看，CLI 是一个独立的 Go 程序，入口为 cli/main.go，通过 Cobra 框架组织命令（见 cli/cmd/root.go）。它除导出照片外还支持导出 Ente Auth 数据的解密等附加能力（见 cli/README.md），但本文聚焦于其在 Ente Photos 中的导出与备份用途。

安装方式

1. 下载预编译二进制（推荐）

官方推荐直接下载预编译二进制。在项目 GitHub Releases 页面中筛选 tag 前缀为cli-v0的发布版本，按平台选择：

• Linux（x64、ARM64）
• macOS（Intel、Apple Silicon）
• Windows（x64）

生成的二进制是独立的静态二进制，无任何外部依赖，可以直接运行，也可以放入 PATH 后全局调用（见 cli/README.md）。

2. 从源码构建

仓库内的 CLI 源码位于 cli，可用如下两种方式构建：

# 一键构建所有平台的发布二进制 ./release.sh # 或仅构建当前平台的单个二进制 go build -o "bin/ente" main.go

构建产物同样是独立静态二进制。当前源码中的版本标识为v0.3.0（见 cli/main.go）。

3. 通过 Docker 运行

仓库同时提供了容器化运行方式（见 cli/README.md），适合 NAS 等以容器为载体的环境：

# 构建并后台启动容器（cli-data 卷为必选，可再挂载导出目录） docker-compose up -d --build # 进入容器执行命令 docker-compose exec ente-cli /bin/sh -c "./ente-cli version" docker-compose exec ente-cli /bin/sh -c "./ente-cli account add"

构建该镜像需要 Docker BuildKit；如遇问题，可在构建命令前加DOCKER_BUILDKIT=1。

验证安装

ente --help # 查看所有可用命令 ente version # 查看版本

账号管理与认证

使用 CLI 前需要先完成认证。官方文档示例为ente account login，而当前仓库源码中实际实现的认证命令是ente account add（见 cli/cmd/account.go 及自动生成的 ente_account_add.md），命令简介即为 “login into existing account”。它会提示输入邮箱和密码，并将会话安全地保存在本地。

需要注意：ente account add不会创建新账号，只是把已存在的账号加入 CLI 的已知账号列表，以便后续执行导出等操作。创建新账号请使用移动端、网页端或桌面应用（见 cli/cmd/account.go）。

CLI 支持管理多个账号（例如你自己和家人成员的账号），可分别配置导出目录，一次性导出所有账号的数据。相关命令一览：

account update的完整参数（依据 ente_account_update.md 与 cli/cmd/account.go）：

导出照片

基本命令

先为账号配置一次导出目录，再执行导出：

# 为账号配置导出目录（每个账号运行一次即可） ente account update --app photos --email you@example.com --dir /path/to/backup # 导出全部照片到已配置的目录 ente export # 只导出指定的相册 ente export --albums "Album Name","Another Album"

ente export的完整参数（依据自动生成的 ente_export.md 与 cli/cmd/export.go）：

这几个过滤器在 cli/pkg/model/filter.go 中实现：--albums/--exclude-albums按相册名（大小写不敏感）匹配，--shared/--hidden则分别依据相册的共享状态与隐藏状态决定是否跳过。

增量导出与断点续传

CLI 的核心优势是增量导出：只下载新增或变更的文件，因此：

• 中断后重新执行ente export会自动从断点继续，不会重复下载；
• 已同步的文件会跳过，运行多次不会产生冗余流量。

这一机制在 cli/pkg/remote_to_disk_file.go 中有明确实现：每次同步先读取远程相册条目，逐条检查SyncedLocally标记，已同步的条目直接跳过（continue）；每个文件下载解密后写入本地，并将“已同步”状态写回本地数据库（UpsertAlbumEntry），下次运行时据此判断。文件删除同样会被镜像到本地（见 cli/pkg/remote_to_disk_file.go）。

用 cron 实现自动化导出

CLI 特别适合脱离交互的定时任务。官方推荐的流程是：先在 cron 之外为账号设置一次导出目录，再把ente export加入计划任务——因为account update是交互式登录，不应放在计划任务里。

# 手动执行一次，设置导出任务使用的目录 /usr/local/bin/ente account update --app photos --email you@example.com --dir /nas/ente-backup # 每天凌晨 2 点自动导出 0 2 * * * /usr/local/bin/ente export

设置步骤：

1. 打开 crontab 编辑器：crontab -e
2. 添加上述 cron 行
3. 保存并退出
4. 用crontab -l验证任务是否生效

Windows 用户可使用“任务计划程序”（Task Scheduler）实现等价功能。FAQ 文档还特别提醒（见 advanced-features.md）：

• 若提示 “CLI not found”，请确保二进制在 PATH 中，或改用完整路径调用；
• 若认证失败，先核对邮箱密码、网络连通性，并确保 CLI 版本为最新；
• 导出中断后直接重跑ente export即可续传。

NAS 同步方案

官方推荐的 NAS 与 Ente 同步方式是用 CLI 把数据从 Ente 拉到 NAS（单向），而非双向同步：

1. 在 NAS 或可访问 NAS 的机器上安装 CLI；
2. 用你的 Ente 账号完成认证（ente account add）；
3. 配置 cron 任务定期执行导出；
4. 依靠增量导出特性保持数据持续同步。

每日同步示例：

/usr/local/bin/ente account update --app photos --email you@example.com --dir /nas/ente-backup 0 2 * * * /usr/local/bin/ente export

[!IMPORTANT]当前不支持双向同步。CLI 只会把 Ente 的数据拉取到本地，本地文件的改动不会同步回 Ente。

FAQ 中针对 NAS 导出的排障建议（见 advanced-features.md）：确保 NAS 挂载点可访问、目标目录有写权限；若 NAS 挂载在本机，使用本地路径。

导出细节：相册结构与元数据

相册结构完整保留

导出会完整保留 Ente 中的相册结构，每个相册对应一个独立文件夹。文件在多个相册中出现时，会出现在每个相册文件夹中（即被多次下载），因此导出体积可能大于 Ente 中统计的存储占用（存储只计一次，见 export.md）。所有共享相册（你分享的和你被分享的）默认都会被导出。

从源码看，相册文件夹的创建逻辑在 cli/pkg/remote_to_disk_album.go：先拉取远程相册列表，为每个未删除的相册创建<相册名>/与<相册名>/.meta/两个目录，并把相册元数据（ID、属主、名称等）写入.meta/album.json；相册被删除时对应文件夹会被移除。文件夹命名经过平台兼容处理（sanitizeAlbumFolderName，见 cli/pkg/remote_to_disk_album.go），会将<>:"/\|?*等非法字符替换为下划线、去除尾部空格与点号，并对 Windows 保留名（CON、NUL、COM1–COM9、LPT1–LPT9 等）加下划线前缀；同名冲突时自动追加_1、_2后缀（uniqueAlbumFolderName）。这些边界情况在 remote_to_disk_album_test.go 中有完整测试用例覆盖。

元数据导出为 JSON（Google Takeout 兼容）

照片原文件不会被修改，元数据以独立 JSON 文件的形式存放在相册目录的.meta子目录中：

photo.jpg .meta/photo.jpg.json

该 JSON 格式与Google Takeout的导出格式一致，因此支持 Google Takeout 导入的工具可以直接读取 Ente 导出的元数据。桌面端与 CLI 的元数据目录名略有差异（见 export.md）：

从源码可以印证：每个文件下载解密后，其磁盘元数据（含原始文件名、唯一文件名列表等）会写入相册目录下的.meta/<唯一文件名>.json（见 cli/pkg/remote_to_disk_file.go）；而本地同步状态则依赖这些.metaJSON 文件与本地 SQLite 数据库（ente-cli.db）共同维护。Live Photos 在导出时会被拆分为独立的图片与视频文件（见 cli/pkg/remote_to_disk_file.go）。

CLI 与桌面端导出的对比

优先选 CLI 的场景：无 GUI 的服务器环境、定时自动化备份、自定义脚本工作流、偏好终端的进阶用户。

优先选桌面端的场景：偏好可视化界面、需要后台持续导出、希望一次性设置不再写脚本。

补充说明：桌面端支持“持续导出”，会自动导出新上传到 Ente 的条目，但前提是桌面应用保持运行；网页端不支持导出，需要导出时请使用桌面端或 CLI（见 export.md）。同时请避免把导出目标目录与“监视上传”的目录设为同一个，否则会造成重复文件、导出停滞等未定义行为（见 export.md）。

配置文件与底层工作原理

CLI 的本地状态和配置都落在用户主目录下的~/.ente目录，也可以借助环境变量ENTE_CLI_CONFIG_DIR（旧版兼容名ENTE_CLI_CONFIG_PATH）重定向（见 cli/main.go）。该目录包含：

• config.yaml：CLI 配置文件，参考 config.yaml.example，可放在$HOME/.ente/config.yaml、当前工作目录或$ENTE_CLI_CONFIG_DIR/config.yaml；
• ente-cli.db：本地 SQLite 数据库，保存账号与会话、远程文件清单、每张照片的同步状态等，运行期间会加锁（同时开多个 CLI 实例会提示超时，见 cli/main.go）。

配置项（见 cli/main.go 与 config.yaml.example）：

CLI 的完整命令文档由 Cobra 自动生成，位于 cli/docs/generated，如需重新生成，运行：

go run main.go docs

（该逻辑见 cli/cmd/root.go 与 cli/main.go。）

相关主题

• 导出功能指南：桌面端导出、导出内容与限制的完整说明；
• 高级功能 FAQ：CLI 安装、认证、导出中断、NAS 同步等常见问题排查；
• CLI 自动生成命令文档：全部子命令的参数速查表；
• CLI README：安装、Docker 用法与源码构建说明。

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