alist 全功能管理

基于 alist REST API 的 Python 客户端，覆盖 alist 全部核心管理功能。

1) 快速开始

python scripts/alist_client.py --base-url http://localhost:80 --username admin --password xxx ping
python scripts/alist_client.py --base-url http://localhost:80 --api-key "your-key" list /mnt/sda2

配置优先级：命令行参数 > 环境变量 (ALIST_BASE_URL, ALIST_USERNAME, ALIST_PASSWORD, ALIST_API_KEY)

Token 自动管理：首次调用自动登录并缓存 token（48h 有效），后续请求自动携带。

2) 全部命令

认证

文件系统

存储管理

用户管理

元信息

设置

任务管理

3) Python API 调用

from alist_client import AlistClient

# 方式一：用户名密码
client = AlistClient("http://localhost:80", "admin", "password")

# 方式二：API Key（无需登录）
client = AlistClient("http://localhost:80", api_key="alist-xxx")

# 文件操作
client.list_files("/mnt/sda2/Downloads")
client.search_files("movie", scope=0)
client.mkdir("/mnt/sda2/电影")
client.rename("/mnt/sda2/test.mp4", "new_name.mp4")
client.move("/mnt/sda2", "/mnt/sda2/电影", ["movie.mp4"])
# 跨存储大文件：增加 timeout（默认查 alist 任务列表验证，避免预占空间误判）
client.move("/mnt/sda2", "/mnt/sdb1/movie", ["movie.mp4"], timeout=3600)
# 跳过验证（不推荐）
client.move("/mnt/sda2", "/mnt/sdb1/", ["x.mp4"], verify=False)
client.remove("/mnt/sda2", ["old_file.mp4"])

# 存储管理
client.storage_list()
client.storage_refresh()
client.storage_enable(1)

# 用户管理
client.user_list()
client.user_create("guest", "pass", role=1)

# 任务管理
client.task_download_list()
client.task_clear_succeeded()

# 树形展示
print(client.tree("/mnt/sda2", depth=2))

# 刮削诊断
diagnosis = client.diagnose_scrape("/电影库NO1/Scream 7 (2026)")
print(diagnosis["verdict"])  # OK / SKIPPED / NOT_SCRAPED / MISCONFIGURED

4) 完整 API 方法列表

5) 代理与 TMDB 刮削

刮削机制

alist 刮削是前端驱动的：用户浏览包含媒体文件的目录时，alist-web（React 前端）从 /api/public/settings 读取 tmdb_api_key，直接构造 TMDB API 请求（POST /api/fs/get 返回文件列表时附带刮削结果）。

关键配置项：

代理配置分层

三层代理配置，互不替代：

┌─────────────────────────────────────────┐
│ 浏览器（用户端）                          │
│ → 直接根据 tmdb_api_url 构造 URL 访问 TMDB │
│ → 需要用户网络能直连 TMDB                 │
├─────────────────────────────────────────┤
│ alist 后端 (Docker 容器)                  │
│ → 通过 http_proxy 设置项 → 宿主机代理      │
│ → Docker 容器必须注入环境变量：             │
│   HTTP_PROXY / HTTPS_PROXY               │
│   http_proxy / https_proxy               │
├─────────────────────────────────────────┤
│ 宿主机代理 (192.168.51.15:7897)           │
│ → 实际出站到 TMDB                         │
└─────────────────────────────────────────┘

Docker 代理注入 (docker-compose.yml)：

environment:
  - HTTP_PROXY=http://192.168.51.15:7897
  - HTTPS_PROXY=http://192.168.51.15:7897
  - http_proxy=http://192.168.51.15:7897
  - https_proxy=http://192.168.51.15:7897

Docker Bridge 网络 HTTPS 502 问题

Docker bridge 网络下，容器通过宿主机代理发起 HTTPS 请求时可能返回 502 Bad Gateway，但 HTTP 请求正常。

解决方案：

1. HTTP 降级（推荐）：tmdb_api_url 设为 http://api.themoviedb.org，走 HTTP 通路
2. host 网络模式：docker-compose.yml 设 network_mode: host，容器直接使用宿主机网络栈

当前环境采用方案 1（HTTP 降级），TMDB HTTP API 功能完整。

setting_save API 调用格式

# 错误（单个对象，设置不生效）
data = {"key": "tmdb_api_url", "value": "http://api.themoviedb.org"}

# 正确（数组）
data = [{"key": "tmdb_api_url", "value": "http://api.themoviedb.org"}]

client.setting_save(data)  # data 必须是 list[dict]

刮削不生效诊断流程

1. 检查 tmdb_api_key：setting_list() → 确认 key 存在且正确
2. 检查 tmdb_api_url：setting_list() → 确认值为 http://api.themoviedb.org（非代理地址）
3. 测试 TMDB 连通性：宿主机 curl http://api.themoviedb.org 确认通
4. 检查 Docker 容器代理：docker exec alist curl -x http://192.168.51.15:7897 http://api.themoviedb.org
5. 检查 NFO 产物：用 get_file() 查看目录下是否有 .nfo 文件，检查修改时间
6. 已有海报跳过问题：若目录已存在 poster.jpg，alist 可能跳过刮削。临时重命名 poster.jpg 后重新访问目录可触发完整刮削过程

重新触发刮削

• 新影片入库：目录无任何元数据文件时，前端浏览目录会自动触发刮削
• 已有海报无 NFO：手动删除/重命名 poster.jpg → 重新访问目录 → 触发完整刮削
• 批量刷新：暂不支持通过 API 批量触发刮削