Immich Power Tools：给 Immich 库做批量整理的非官方客户端
用于组织您的 immich 图书馆的强大工具。 Immich Power Tools 一个非官方的 immich 客户端，提供更好的工具来组织和管理您的 immich 帐户。
秒懂
- 它是什么？
- Immich Power Tools 是一个面向 Immich 用户的非官方客户端，用批量操作弥补官方界面在人物、相册和位置整理上的不足。它直接连数据库，功能强，但部署和权限要求也更高。
- 适合谁用？
- 适合已经用 Immich 管理大量照片、并且厌倦了逐张编辑人物的用户。它把人物合并、日期偏移、位置补齐这些高频操作做成了批量动作，能省下大量重复劳动。
- 能商用吗？
- 可以，但条件严格。AGPL-3.0 是网络 copyleft 许可证：如果别人通过网络使用你修改过的版本（例如作为托管服务），你必须以同一许可证向他们提供源代码。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是 Immich 官方界面做不了的事
Immich 的官方界面适合浏览和备份，但批量整理很吃力。作者在 README 里写得很直白：他从 Google Photos 迁移到 Immich 后，发现人物匹配和批量操作严重缺失，每次都得打开单个资产手动处理。Immich Power Tools 就是为这个场景做的。它不是一个通用管理面板，而是专门针对人物、相册、位置和日期这四个维度的批量工具。目标用户很明确：照片量大、需要成批修正元数据、或者想靠相似度建议合并人物的 Immich 重度用户。
直连数据库，这是它和普通 API 客户端的本质区别
大多数 Immich 第三方工具只走 API，Immich Power Tools 不是。部署时除了要填 IMMICH_API_KEY 和 IMMICH_URL，还强制要求 DB_HOST 和 DB_PORT，也就是要直连 Immich 的 Postgres 数据库。这个设计让它能拿到 API 拿不到的数据，比如跨资产的人物相似度分析，这是 Smart Merge 和 Potential Albums 这类功能的基础。代价是部署复杂度上升，你必须知道数据库容器名，还要把 power-tools 容器放进 Immich 所在的 Docker 网络。README 里给的方案是 docker compose 里加一个服务，或者用 docker network connect 手动接进去。
部署方式：compose 文件加环境变量，没有更简单的路径
官方推荐用 Docker Compose。在现有的 immich compose 文件里加一个 power-tools 服务，镜像来自 ghcr.io/immich-power-tools/immich-power-tools:latest，挂一个数据卷，映射 8001 端口到容器内的 3000。环境变量方面，IMMICH_API_KEY 和 IMMICH_URL 是必填，DB_HOST 默认写 immich_postgres，DB_PORT 默认 5432。本地开发则用 bun，复制 .env.example 后填上数据库用户名、密码、库名。有个细节要注意：README 明确说创建 API key 时必须勾选所有权限，这意味着这个工具需要的是完全访问权，不是最小权限。
六个核心功能，人物合并是重头戏
功能列表里最突出的是 People Merge Suggestion，它基于人脸相似度给出合并建议，支持批量合并。这直接对应作者在 back story 里抱怨的痛点。其次是批量更新人物数据，带高级筛选。Missing Location 功能会找出没有位置信息的资产，用同一资产的其他位置信息去补。Bulk Date Offset 用来修正时区或设备时钟错误导致的日期偏移，按选定资产统一加减时间。Potential Albums 会根据资产和人物关系推荐可能想创建的相册。Analytics 提供资产时间分布和 EXIF 统计。最后是 Smart Search，用自然语言搜索，比如查 2024 年某个人的所有照片。
Smart Search 依赖外部 AI，数据边界要看清
Smart Search 不是本地实现的。它需要配置 AI_API_KEY、AI_BASE_URL 和 AI_MODEL，接的是 OpenAI 兼容接口。README 里给了 OpenAI、Groq、Ollama 和 LM Studio 作为选项。关键限制是：发送给 AI 提供商的只有你的搜索文本，不是整个媒体库。这是一个明确的数据边界，但也要注意，如果你的搜索词里包含人名或地点，这些信息仍然会离开你的服务器。用 Ollama 跑本地模型可以完全避免外发，但 README 没有给出任何本地模型的具体配置示例，只给了 base URL 的格式，实际效果需要你自己试。
Google Maps 只用于热力图，且只发位置数据
另一个外部依赖是 Google Maps，用在资产地理热力图上。README 特意强调，渲染热力图时只把位置数据发给 Google Maps，其他数据不发，还引用了 src/pages/assets/geo-heatmap.tsx 的第 32 行作为代码依据。这意味着位置信息本身会出网。如果你对地理隐私敏感，这个功能可以不用，它不影响其他工具的运行。但要注意，热力图是 Analytics 的一部分，关掉它就少了一个可视化维度。
版本兼容是硬约束，v0.22.0 起绑定 Immich 3.0
README 里有一个 IMPORTANT 级别的警告：v0.22.0 及以上版本要求 Immich 3.0 或更新。这不是建议，是硬性要求。如果你的 Immich 还在 2.x，要么升级 Immich，要么停留在旧版 Power Tools。仓库的 release 记录显示，v0.22.0 发布于 2026 年 7 月，v0.21.4 在同年 5 月，更新节奏大约是两个月一个版本。这意味着 Immich 主程序升级时，Power Tools 可能也需要跟着升。选型时要考虑这个维护成本：你不是在装一个静态工具，而是在追一个跟主程序版本绑定的附属项目。
替代方案与边界：官方 CLI 和 Immich 自身的批量能力
如果你不想让第三方容器直连数据库，Immich 官方 CLI 是更保守的选择。它能做上传、备份和部分资产管理，但不会有人物相似度合并或潜在相册推荐，因为那些需要数据库级别的分析。另一个思路是等 Immich 官方把批量整理功能做进主界面，但作者做这个工具本身就说明官方进度不够快。Power Tools 的定位是填补官方空白，代价是它要求 API key 全权限加数据库直连，这两个条件本身就是安全上的妥协。适合愿意接受这个风险、并且确实有批量整理刚需的用户。不适合把 Immich 当纯备份仓库、很少整理元数据的人。
编辑结论
适合已经用 Immich 管理大量照片、并且厌倦了逐张编辑人物的用户。它把人物合并、日期偏移、位置补齐这些高频操作做成了批量动作，能省下大量重复劳动。不适合只想偶尔整理几张照片的人，也不适合不愿意给 API key 开全部权限、或者不想让第三方容器直连 Postgres 的用户。部署前先确认三件事：Immich 版本是否在 3.0 及以上，API key 是否勾选了全部权限，数据库容器名和网络是否与 compose 文件里写的一致。这个工具的价值建立在它对你 Immich 实例的深度访问之上，权限给得越全，它能做的事越多，风险也越大。
社区笔记