跳转至

开始使用

桌面应用

从 GitHub Releases 下载对应平台的安装包:

  • macOS: 下载 zip, 解压后将 Amane.app 拖入 Applications. 常驻菜单栏, 一键打开 Web 界面.
  • Windows: 下载 zip 解压, 运行 Amane.exe. 常驻系统托盘, 一键打开 Web 界面.

桌面应用内置服务监督, 崩溃自动重启.

Docker

推荐使用 Docker Compose 部署. 将以下内容保存为 compose.yaml, 修改 /path/to/media 为你的媒体目录:

services:
  amane:
    image: ghcr.io/sqzw-x/amane:latest
    container_name: amane
    user: "${UID:-1000}:${GID:-1000}"
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data
      - /path/to/media:/media
    environment:
      - AMANE_DATA_DIR=/data
      - AMANE_LOG_LEVEL=INFO
      - AMANE_SUPERVISED=1
    restart: unless-stopped

docker compose up -d

也可以直接运行:

docker run -d --name amane \
  --user "$(id -u):$(id -g)" \
  -p 8000:8000 \
  -v "$PWD/data:/data" \
  -v /path/to/media:/media \
  -e AMANE_DATA_DIR=/data \
  ghcr.io/sqzw-x/amane:latest

启动后访问 http://localhost:8000.

源码安装

前置依赖:

  • uv — Python 包管理
  • pnpm — 前端包管理
  • just — 任务运行器
git clone https://github.com/sqzw-x/amane.git
cd amane
just setup   # 同步依赖
just dev     # 启动 API (:8000) + 前端开发服务器

首次登录

启动服务后, 浏览器访问 http://localhost:8000 (桌面应用会自动打开).

首次访问需要输入 API Token:

  • 桌面应用: 在菜单栏/托盘图标中点击「复制 Token」, 粘贴到浏览器即可
  • Docker: 运行 docker logs amane 查看启动日志中的 Token
  • 源码: 查看终端输出中的 Token

Tip

Token 仅需输入一次, 浏览器会通过 HttpOnly Cookie 保持登录状态.

添加媒体库

登录后, 进入「管理 → 媒体库」页面创建你的第一个媒体库:

  1. 点击「添加库」
  2. 设置库名称
  3. 设置媒体目录路径 (需在 Docker 挂载范围内)
  4. 选择自动化级别:
  5. 不自动: 仅手动扫描
  6. 仅监控: 文件变化时自动注册
  7. 监控+刮削: 文件变化时自动注册并刮削
  8. 配置路径模板 (可使用默认值)

创建后, 点击「扫描」按钮开始首次扫描, 或等待文件监控自动发现.

下一步