# 部署说明（Docker/本地）

本项目提供一个基于 Fastify 的文件代理与缩略图服务，依赖 sharp 与 ffmpeg 生成图片/视频缩略图。核心服务入口为 [fastify.js](file:///Users/x/Project/alist-proxy/index.js)，Docker 配置见 [Dockerfile](file:///Users/x/Project/alist-proxy/Dockerfile)。

## 本地直接运行
- 环境要求：Node.js 18+（推荐 22），pnpm 或 npm
- 安装依赖：

```bash
pnpm install
# 或
npm install
```

- 启动服务：

```bash
node index.js
```

- 访问：`http://localhost:9520/`

## 使用 Docker（本机）
- 构建镜像：

```bash
docker build -t alist-proxy .
```

- 运行容器（挂载缓存目录）：

```bash
docker run --rm -p 9520:9520 -v "$PWD/.cache:/app/.cache" alist-proxy
```

- 访问：`http://localhost:9520/`

说明：
- 镜像基于 `mcr.microsoft.com/devcontainers/javascript-node:22` 并安装 ffmpeg，以支持视频缩略图。
- 服务默认监听端口 `9520`，容器中入口命令为 `node index.js`。

## 在其它服务器运行
若服务器无法从公共仓库拉取镜像（例如出现 `context deadline exceeded`），可使用以下任一方式：

- 方式 A：在本机构建后离线传输到服务器
  1) 根据服务器架构制作镜像包：
  
  - 服务器架构为 amd64：
  
  ```bash
  docker buildx create --use
  docker buildx build --platform linux/amd64 -t alist-proxy:latest --output type=docker,dest=alist-proxy-amd64.tar .
  ```
  
  - 服务器架构为 arm64：
  
  ```bash
  docker save alist-proxy:latest -o alist-proxy-arm64.tar
  ```
  
  2) 传到服务器并加载运行：
  
  ```bash
  scp alist-proxy-*.tar root@SERVER_IP:/www/wwwroot/filesystem/
  ssh root@SERVER_IP
  cd /www/wwwroot/filesystem
  docker load -i alist-proxy-amd64.tar   # 或 alist-proxy-arm64.tar
  mkdir -p /www/wwwroot/filesystem/.cache
  docker run --rm -p 9520:9520 -v "/www/wwwroot/filesystem/.cache:/app/.cache" alist-proxy
  ```

- 方式 B：在服务器本地构建镜像
  1) 将项目目录拷贝到服务器（git clone 或 scp）
  2) 在服务器执行：
  
  ```bash
  cd /www/wwwroot/filesystem
  docker build -t alist-proxy .
  mkdir -p /www/wwwroot/filesystem/.cache
  docker run --rm -p 9520:9520 -v "/www/wwwroot/filesystem/.cache:/app/.cache" alist-proxy
  ```
  
  若同样无法拉取基础镜像，可配置加速器后重试：
  
  ```bash
  # /etc/docker/daemon.json
  {
    "registry-mirrors": [
      "https://hub-mirror.c.163.com",
      "https://docker.mirrors.ustc.edu.cn"
    ]
  }
  systemctl daemon-reload && systemctl restart docker
  ```

- 方式 C：使用私有/企业镜像仓库
  1) 在本机推送镜像到你的仓库：
  
  ```bash
  docker tag alist-proxy registry.example.com/namespace/alist-proxy:latest
  docker push registry.example.com/namespace/alist-proxy:latest
  ```
  
  2) 服务器拉取并运行：
  
  ```bash
  docker pull registry.example.com/namespace/alist-proxy:latest
  docker run --rm -p 9520:9520 -v "/www/wwwroot/filesystem/.cache:/app/.cache" registry.example.com/namespace/alist-proxy:latest
  ```

## API 可达性
- 代码中默认 `API_BASE = http://127.0.0.1:9558/api`，容器内的 `127.0.0.1` 指向容器自身。
- 若 API 不在同一容器或主机，请确保容器能访问到 API（例如使用宿主机 IP、`host.docker.internal` 或将 API 同样容器化并加入同一网络）。
- 如需通过环境变量覆盖 API 地址，可在代码中改为读取环境变量后再构建镜像。

## 缓存与持久化
- 缓存路径：/.cache`，建议以卷挂载到宿主机以持久化。
- 示例挂载：`-v "/宿主路径/.cache:/app/.cache"`

## 常见问题
- 拉取镜像超时：使用离线 tar 包（见“在其它服务器运行”）。
- 端口不可访问：检查服务器安全组/防火墙是否开放 `9520`。
- 架构不匹配：根据服务器架构选择 `linux/amd64` 或 `linux/arm64` 生成镜像。