一、环境准备：构建基础运行环境

1.1 安装Node.js运行时环境

在Linux服务器环境中，推荐使用系统包管理器安装Node.js基础环境：

sudo apt update
sudo apt install -y nodejs npm

安装完成后建议验证版本信息：

node -v  # 推荐使用v18.x或更高版本
npm -v

1.2 配置国内镜像加速

为提升依赖安装速度，建议将npm注册表源切换至国内镜像：

npm config set registry https://registry.npmmirror.com

可通过以下命令验证配置是否生效：

npm config get registry

二、工具链安装与版本管理

2.1 安装最新版CLI工具

传统教程中使用的npm i -g immich命令已失效，需使用官方维护的命名空间版本：

npm install -g @immich/cli

安装完成后建议创建软链接确保全局调用：

sudo ln -s $(which immich) /usr/local/bin/immich

2.2 Node.js版本升级方案

当系统提示Node.js版本过低时，推荐使用n工具进行版本管理：

# 安装版本管理工具
sudo npm install -g n
# 升级至稳定版本
sudo n stable
# 验证升级结果
node -v

升级后建议重启终端会话或执行hash -r清除命令缓存。

三、API密钥安全获取流程

3.1 密钥生成步骤

登录Web管理界面（默认端口2283）
点击右上角用户头像进入账户设置
在”API密钥”选项卡点击”生成新密钥”
复制生成的密钥字符串（格式示例：6Y0wmmLv9QuPqXAT）

3.2 密钥存储建议

推荐将密钥保存在加密的配置文件中：

mkdir -p ~/.immich/
echo "API_KEY=your_generated_key" > ~/.immich/config.env
chmod 600 ~/.immich/config.env

四、安全认证与会话管理

4.1 交互式登录认证

使用以下命令启动认证流程：

immich login http://<服务器IP>:2283/api

系统会提示输入API密钥，输入后自动建立安全会话。认证成功后建议保存会话令牌：

# 查看当前会话信息
immich whoami

4.2 非交互式认证方案

对于自动化脚本场景，可通过环境变量传递凭证：

export IMMICH_API_KEY="your_api_key"
export IMMICH_SERVER_URL="http://<ip>:2283/api"
immich upload --recursive /path/to/files

五、批量上传实施指南

5.1 基础上传命令

immich upload --recursive /vol3/1000/Downloads/Picture

关键参数说明：

--recursive：递归处理子目录
支持绝对路径和相对路径
路径中避免使用特殊字符

5.2 高级上传选项

排除特定文件：

immich upload --recursive --exclude "*.tmp" --exclude "*.bak" /data/photos

带宽限制（适用于低带宽环境）：

immich upload --recursive --limit-rate 1024k /media/videos

断点续传（需服务器支持）：

immich upload --recursive --chunk-size 10M /large_files

六、常见问题排查

6.1 认证失败处理

检查服务器防火墙是否开放2283端口
验证API密钥是否过期（有效期默认90天）
确认系统时间同步（NTP服务状态）

6.2 上传中断修复

查看详细日志：

immich upload --verbose --recursive /path

网络问题排查：
```bash

测试基础连通性

curl -I http://:2283/api/health

检查SSL证书（自签名证书需添加—insecure参数）


3. 磁盘空间检查：
```bash
df -h /target_mount_point

6.3 性能优化建议

对于TB级数据上传，建议分批次处理（每次<50GB）
使用SSD作为临时存储介质
调整内核参数：
```bash

临时调整

sudo sysctl -w vm.dirty_background_ratio=10
sudo sysctl -w vm.dirty_ratio=20

永久生效（需写入/etc/sysctl.conf）

```

七、最佳实践总结

环境隔离：建议为媒体管理创建独立用户
自动化运维：编写Shell脚本封装常用操作
监控告警：集成日志分析工具监控上传状态
定期维护：每月检查API密钥有效期和存储配额

通过系统化的操作流程和完善的错误处理机制，开发者可以高效管理私有化部署环境中的媒体资源。本方案特别适用于需要处理大量图片/视频的科研机构、影像工作室等场景，在保证数据安全性的同时提供接近云服务的操作体验。

私有化部署环境下的媒体管理工具操作指南：命令行上传与认证全流程