Immich 服务器管理 CLI 详解immich-admin 命令、执行方式与底层实现【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 的immich-server镜像内置了一个名为immich-admin的管理员命令行工具用于在 Web 界面之外完成重置管理员密码、开关维护模式、管理 OAuth/密码登录、调整管理员权限、修改媒体存储路径等日常运维操作。本文基于仓库中的 官方文档 完整覆盖每一条命令的用法与输出示例并结合 server 端命令实现源码 讲解各命令背后的服务调用链帮助你既能照着执行也能理解每条命令实际改动了什么。immich-admin 命令一览immich-admin支持以下命令与 server-commands.md 中列表完全一致命令说明help显示帮助信息reset-admin-password重置管理员用户的密码disable-password-login禁用密码登录enable-password-login启用密码登录disable-maintenance-mode关闭维护模式enable-maintenance-mode开启维护模式enable-oauth-login启用 OAuth 登录disable-oauth-login禁用 OAuth 登录list-users列出 Immich 用户grant-admin按邮箱授予用户管理员权限revoke-admin按邮箱撤销用户管理员权限version打印 Immich 版本change-media-location修改数据库中的文件路径以匹配新的媒体存储位置schema-check校验数据库迁移状态并检查 schema 漂移schema drift所有命令都注册在 commands 索引文件 的commandsAndQuestions数组中通过nest-commander框架统一注册为ImmichAdminModule的子命令。如何执行命令执行方式引自 docker-help 指南先连接到immich_server容器再通过immich-admin command执行# 进入 immich_server 容器的交互式 Shell docker exec -it immich_server bash # 在容器内执行管理命令 immich-admin command从源码结构看immich-admin并非独立二进制而是复用服务器入口容器启动脚本 start.sh 会检测第一个参数若为immich-admin则进入安静模式QUIETtrue最终由 main.ts 识别该参数将进程标题设为immich_admin_cli、日志级别提升到Warn然后调用CommandFactory.run(ImmichAdminModule)启动 CLI而不是启动常驻的 worker 进程。容器内的入口脚本 immich-admin 只是一行start.sh immich-admin $的包装。这意味着所有管理命令都运行在服务器容器环境内能直接访问数据库与环境变量如IMMICH_MEDIA_LOCATION因此不需要额外凭据即可操作本机配置。重置管理员密码immich-admin reset-admin-password Found Admin: - IDe65e6f88-2a30-4dbe-8dd9-1885f4889b53 - OAuth ID - Emailadminexample.com - NameImmich Admin ? Please choose a new password (optional) immich-is-cool ? Invalidate existing sessions? Yes The admin password has been updated.交互式流程有两步可选地输入新密码以及确认是否使现有会话失效默认 Yes。结合 reset-admin-password.command.ts 与 cli.service.ts 的实现具体行为是通过userRepository.getAdmin()查找管理员账户如果不存在则直接报错Admin account does not exist。打印管理员的 ID、OAuth ID、邮箱、姓名方便确认操作对象。若未输入新密码服务端会调用cryptoRepository.randomBytesAsText(24)随机生成一个密码并在终端打印出来provided: false分支若输入了密码则提示The admin password has been updated.。密码一律经 bcrypthashBcrypt哈希后写入数据库明文不落库。若确认失效会话则调用sessionRepository.invalidateAll({ userId })吊销该管理员的全部登录会话——在密码疑似泄露的场景下这一步尤其关键。禁用 / 启用密码登录immich-admin disable-password-login Password login has been disabled.immich-admin enable-password-login Password login has been enabled.从 cli.service.ts 的实现看这两个命令本质是修改应用配置中的passwordLogin.enabled字段getConfig({ withCache: false })读取后updateConfig写回因此效果立即持久化重启后依然生效。典型使用场景在已配置 OAuth 的企业环境中关闭密码登录只允许 SSO 入口。维护模式immich-admin enable-maintenance-mode Maintenance mode has been enabled. Log in using the following URL: https://my.immich.app/maintenance?tokentokenimmich-admin disable-maintenance-mode Maintenance mode has been disabled.开启维护模式会输出一个带 token 的登录 URL用于在系统维护期间临时登录。源码 maintenance-mode.ts 的enable-maintenance-mode描述为“Enable maintenance mode or regenerate the maintenance token”即重复执行可以重新生成 token若服务器已处于维护模式会提示The server is already in maintenance mode!并复用已有 secret。cli.service.ts 中enableMaintenanceMode的完整流程可以印证这一点从systemMetadata表读取SystemMetadataKey.MaintenanceMode状态若未启用则generateMaintenanceSecret()生成随机密钥写入isMaintenanceMode: true与action: MaintenanceAction.Start调用appRepository.sendOneShotAppRestart({ isMaintenanceMode: true })通知 worker 重启使维护模式生效基于外部域名与{ username: cli-admin }载荷拼出authUrl打印到终端。关闭维护模式则提示Maintenance mode has been disabled.若本来就不在维护模式会提示The server is already out of maintenance mode!。启用 / 禁用 OAuth 登录immich-admin enable-oauth-login OAuth login has been enabled.immich-admin disable-oauth-login OAuth login has been disabled.对应实现见 oauth-login.ts两个命令分别调用CliService的enableOAuthLogin()/disableOAuthLogin()修改系统配置中的 OAuth 开关。OAuth 的具体提供方配置issuer、clientId、clientSecret 等环境变量则需要在 OAuth 文档 对应的部署环境层面完成CLI 只负责开关。列出用户immich-admin list-users [ { id: e65e6f88-2a30-4dbe-8dd9-1885f4889b53, email: immichexample.com, name: Immich Admin, storageLabel: admin, externalPath: null, profileImagePath: upload/profile/e65e6f88-2a30-4dbe-8dd9-1885f4889b53/e65e6f88-2a30-4dbe-8dd9-1885f4889b53.jpg, shouldChangePassword: true, isAdmin: true, createdAt: 2023-07-11T20:12:20.602Z, deletedAt: null, updatedAt: 2023-09-21T15:42:28.129Z, oauthId: , } ]输出为完整的用户对象数组包含 ID、邮箱、显示名、存储标签、头像路径、shouldChangePassword、isAdmin、创建/删除/更新时间等字段。该输出可以直接作为grant-admin/revoke-admin前的确认步骤——先看清目标用户的邮箱再操作。授予 / 撤销管理员权限immich-admin grant-admin ? Please enter the user email: userexample.com Admin access has been granted to userexample.comimmich-admin revoke-admin ? Please enter the user email: userexample.com Admin access has been revoked from userexample.com两个命令均以邮箱定位目标用户交互式提示Please enter the user email:实现见 grant-admin.ts提示输入后分别调用CliService.grantAdminAccess(email)/revokeAdminAccess(email)失败时打印Unable to grant/revoke admin access to user。一个值得注意的细节GrantAdminCommand与RevokeAdminCommand的成功提示使用的是console.debug(...)而日志级别在 CLI 模式下被设为Warn见 main.ts因此成功时可能不打印文档示例中的那行提示——命令无报错即视为成功必要时可用list-users复核isAdmin字段。查看版本immich-admin version v1.129.0version.command.ts 通过VersionService.getVersion()读取镜像构建时注入的版本信息以v{major}.{minor}.{patch}形式打印。适合在升级前确认线上运行的确切版本。修改媒体存储位置change-media-location当你把媒体卷从容器内路径/data迁移到/my-data时只改挂载是不行的——数据库里记录的每一张资产、人物缩略图、用户头像路径都还带着旧前缀。change-media-location命令用于批量改写这些路径immich-admin change-media-location ? Enter the previous value of IMMICH_MEDIA_LOCATION: /data ? Enter the new value of IMMICH_MEDIA_LOCATION: /my-data ... Previous value: /data Current value: /my-data Changing database paths from /data/* to /my-data/* ? Do you want to proceed? [Y/n] y Database file paths updated successfully! ...命令的完整交互流程结合 media-location.command.ts展示样例路径先调用CliService.getSampleFilePaths()从资产、人物、用户三类表中各取若干条真实路径asset.path、人物thumbnailPath、用户profileImagePath打印出来帮助你确认旧值拼写正确询问新旧值提示词会带上当前环境变量IMMICH_MEDIA_LOCATION作为默认值Enter the previous value of IMMICH_MEDIA_LOCATION: [当前值]直接回车即采用确认迁移打印Changing from 旧值/* to 新值/*并要求[Y/n]确认执行迁移CliService.migrateFilePaths会做两项校验——旧值若以./开头会自动剥掉新值必须是绝对路径否则抛Target media location must be an absolute path——确认后才调用databaseRepository.migrateFilePaths批量更新数据库。成功后命令还会提示两个后续动作设置IMMICH_MEDIA_LOCATION新值并重启以及同步更新 compose 文件中的卷挂载源码中的提示示例形如volumes: - \${UPLOAD_LOCATION}:/data。若没有匹配的行则输出No rows were updated。检查数据库迁移与 schema 漂移schema-checkimmich-admin schema-check Migrations are up to date No schema drift detected这是排查“升级后行为异常”的第一站命令。schema-check.ts 会输出两类诊断结果迁移文件状态逐条核对磁盘上的迁移文件与数据库已应用记录状态分三类applied—— 已应用且文件存在正常deleted—— 已应用到数据库但迁移文件在磁盘上消失了missing—— 迁移文件存在但尚未应用到数据库。任何非applied状态都会打印Migration issues detected:及具体说明。Schema 漂移对比数据库实际表结构与代码期望结构。无漂移时输出No schema drift detected有漂移时打印每一项差异经asHuman格式化为可读文本并自动生成一段修复用 SQL供参考同时明确标注 “Use at your own risk!”——这段 SQL 只是辅助排查的提示不建议在生产库上盲目执行。小结进入方式固定docker exec -it immich_server bash后执行immich-admin command参见 docker-help 指南账号类命令reset-admin-password、grant-admin、revoke-admin均为交互式操作前建议先用list-users核对目标配置类命令密码/OAuth 登录开关、维护模式直接改写系统配置元数据并持久化重启后依然生效change-media-location是媒体卷迁移的关键一步它只改数据库中的路径前缀卷挂载与IMMICH_MEDIA_LOCATION环境变量仍需自行同步修改升级或数据库异常时优先运行schema-check其输出的迁移状态与自动生成的漂移 SQL 是排查的重要依据。所有命令的源码实现集中在 server/src/commands/ 目录共享的服务层逻辑配置读写、密码哈希、路径迁移、维护密钥生成等位于 server/src/services/cli.service.ts可按需进一步阅读。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考