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 环境偏好命令行的进阶用户定时任务借助 cronLinux/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的发布版本按平台选择Linuxx64、ARM64macOSIntel、Apple SiliconWindowsx64生成的二进制是独立的静态二进制无任何外部依赖可以直接运行也可以放入 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_BUILDKIT1。验证安装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 支持管理多个账号例如你自己和家人成员的账号可分别配置导出目录一次性导出所有账号的数据。相关命令一览命令说明ente account add登录并添加一个已存在的账号ente account list列出已配置的账号ente account update --app app --email email --dir 目录修改指定账号在指定应用下的导出目录ente account get-token --app app --email email获取指定账号在指定应用下的 tokenaccount update的完整参数依据 ente_account_update.md 与 cli/cmd/account.go参数类型默认值说明--dirstring—导出目录必填dir未指定会报错--emailstring—账号邮箱必填email未指定会报错--appstringphotos指定应用源码校验的可选值为photos、locker、auth见 cli/cmd/account.go导出照片基本命令先为账号配置一次导出目录再执行导出# 为账号配置导出目录每个账号运行一次即可 ente account update --app photos --email youexample.com --dir /path/to/backup # 导出全部照片到已配置的目录 ente export # 只导出指定的相册 ente export --albums Album Name,Another Albumente export的完整参数依据自动生成的 ente_export.md 与 cli/cmd/export.go参数类型默认值说明--albums strings逗号分隔列表空要导出的相册名列表--emails strings逗号分隔列表空只导出与这些邮箱共享的文件--exclude-albums strings逗号分隔列表空要排除的相册名列表--sharedbooltrue传递--sharedfalse可排除共享相册--hiddenbooltrue传递--hiddenfalse可排除隐藏相册这几个过滤器在 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 youexample.com --dir /nas/ente-backup # 每天凌晨 2 点自动导出 0 2 * * * /usr/local/bin/ente export设置步骤打开 crontab 编辑器crontab -e添加上述 cron 行保存并退出用crontab -l验证任务是否生效Windows 用户可使用“任务计划程序”Task Scheduler实现等价功能。FAQ 文档还特别提醒见 advanced-features.md若提示 “CLI not found”请确保二进制在 PATH 中或改用完整路径调用若认证失败先核对邮箱密码、网络连通性并确保 CLI 版本为最新导出中断后直接重跑ente export即可续传。NAS 同步方案官方推荐的 NAS 与 Ente 同步方式是用 CLI 把数据从 Ente 拉到 NAS单向而非双向同步在 NAS 或可访问 NAS 的机器上安装 CLI用你的 Ente 账号完成认证ente account add配置 cron 任务定期执行导出依靠增量导出特性保持数据持续同步。每日同步示例/usr/local/bin/ente account update --app photos --email youexample.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 中有完整测试用例覆盖。元数据导出为 JSONGoogle Takeout 兼容照片原文件不会被修改元数据以独立 JSON 文件的形式存放在相册目录的.meta子目录中photo.jpg .meta/photo.jpg.json该 JSON 格式与Google Takeout的导出格式一致因此支持 Google Takeout 导入的工具可以直接读取 Ente 导出的元数据。桌面端与 CLI 的元数据目录名略有差异见 export.md导出方式元数据格式Ente Desktopphoto.jpgmetadata/photo.jpg.jsonEnte CLIphoto.jpg.meta/photo.jpg.json从源码可以印证每个文件下载解密后其磁盘元数据含原始文件名、唯一文件名列表等会写入相册目录下的.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自动化✅ cron、脚本✅ 持续导出服务器使用✅ 无头服务器❌ 需要 GUI相册选择命令行参数GUI 设置增量导出✅✅元数据✅✅优先选 CLI 的场景无 GUI 的服务器环境、定时自动化备份、自定义脚本工作流、偏好终端的进阶用户。优先选桌面端的场景偏好可视化界面、需要后台持续导出、希望一次性设置不再写脚本。补充说明桌面端支持“持续导出”会自动导出新上传到 Ente 的条目但前提是桌面应用保持运行网页端不支持导出需要导出时请使用桌面端或 CLI见 export.md。同时请避免把导出目标目录与“监视上传”的目录设为同一个否则会造成重复文件、导出停滞等未定义行为见 export.md。配置文件与底层工作原理CLI 的本地状态和配置都落在用户主目录下的~/.ente目录也可以借助环境变量ENTE_CLI_CONFIG_DIR旧版兼容名ENTE_CLI_CONFIG_PATH重定向见 cli/main.go。该目录包含config.yamlCLI 配置文件参考 config.yaml.example可放在$HOME/.ente/config.yaml、当前工作目录或$ENTE_CLI_CONFIG_DIR/config.yamlente-cli.db本地 SQLite 数据库保存账号与会话、远程文件清单、每张照片的同步状态等运行期间会加锁同时开多个 CLI 实例会提示超时见 cli/main.go。配置项见 cli/main.go 与 config.yaml.example配置键默认值说明endpoint.apiEnte 官方 API 地址API 端点自建服务器用户可改为自己的端点log.httpfalse是否打印每个 HTTP 请求的状态码与耗时CLI 的完整命令文档由 Cobra 自动生成位于 cli/docs/generated如需重新生成运行go run main.go docs该逻辑见 cli/cmd/root.go 与 cli/main.go。相关主题导出功能指南桌面端导出、导出内容与限制的完整说明高级功能 FAQCLI 安装、认证、导出中断、NAS 同步等常见问题排查CLI 自动生成命令文档全部子命令的参数速查表CLI README安装、Docker 用法与源码构建说明。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考