Docker Hub 镜像（推荐）#

镜像地址：docker.io/charyeahowo/nyaovo-random-image-api:latest

docker compose 部署（点击展开）

创建 docker-compose.yml，复制以下内容，修改 ADMIN_PASSWORD 和 SESSION_SECRET：

1
services:
2
  nyaovo-random-image-api:
3
    image: charyeahowo/nyaovo-random-image-api:latest
4
    container_name: nyaovo-random-image-api
5
    ports:
6
      - "3400:3000"
7
    volumes:
8
      - ./images:/app/public/images
9
    environment:
10
      PORT: 3000
11
      PUBLIC_BASE_URL: http://localhost:3400
12
      IMAGE_ROOT: public/images
13
      CACHE_TTL_SECONDS: 60
14
      RATE_LIMIT_WINDOW_MS: 60000
15
      RATE_LIMIT_MAX: 120
16
      ADMIN_USERNAME: admin
17
      ADMIN_PASSWORD: changeme          # ← 务必修改
18
      SESSION_SECRET: please-change-this # ← 务必修改
19
      ADMIN_PATH: /image/admin
20
      MAX_FILE_SIZE_MB: 10
21
      MAX_UPLOAD_FILES: 20
22
      CORS_ORIGIN: "*"
23
    restart: unless-stopped

1
docker compose up -d

容器启动时会自动修复 ./images 目录权限，无需手动 chown。

如果是从旧版本升级，首次启动可能需要几秒完成权限修复。

访问 http://localhost:3400/image，后台 http://localhost:3400/image/admin。

docker run 部署（点击展开）

1
docker run -d \
2
  --name nyaovo \
3
  -p 3400:3000 \
4
  -v ./images:/app/public/images \
5
  -e ADMIN_PASSWORD=your-password \
6
  -e SESSION_SECRET=your-secret \
7
  -e PUBLIC_BASE_URL=http://localhost:3400 \
8
  --restart unless-stopped \
9
  charyeahowo/nyaovo-random-image-api:latest

挂载的 images 目录需要写权限，不要加 :ro。

本地构建部署（点击展开）

1
git clone https://github.com/charyeahowo/nyaovo-random-image-api.git
2
cd nyaovo-random-image-api
3

4
cp .env.example .env
5
# 编辑 .env，至少修改 ADMIN_PASSWORD 和 SESSION_SECRET
6

7
docker compose up -d --build

如需使用本地构建而非远程镜像，请将 docker-compose.yml 中的 image 行替换为：

1
build:
2
  context: .
3
  dockerfile: Dockerfile

1Panel 部署（点击展开）

1. 新建 Docker Compose 编排，上传项目或 Git 拉取
2. 使用项目自带 docker-compose.yml，创建 .env 文件填写环境变量
3. 启动后在 OpenResty / Nginx 配置反向代理绑定域名

本地运行#

1
npm install
2
cp .env.example .env   # 编辑配置
3
npm start               # 或 npm run dev 热更新

默认账号 admin，默认密码 changeme。

Cloudflare Worker + R2 公开 API#

如果只想把随机图公开访问迁移到 Cloudflare，保留现有后台和 Docker 部署不变，可以使用新增的 Worker + R2 方案：

• Worker 代码和 Wrangler 配置位于 cloudflare/
• 迁移脚本：npm run cloudflare:manifest
• 部署说明见 cloudflare/README.md

第一阶段只承载 /image/api/... 和 /image/images/... 的公开访问能力，后台管理仍使用当前 Express 项目。

EdgeOne Pages + Edge Functions 公开 API#

如果主要面向国内访问加速，或想用腾讯云 EdgeOne Pages 做轻量公开访问层，可以使用新增的 EdgeOne 方案：

• EdgeOne 代码、Pages 配置和文档位于 edgeone/
• 迁移脚本：npm run edgeone:manifest
• 部署说明见 edgeone/README.md

第一阶段只迁移随机图、图库列表、图片列表、统计和健康检查等公开接口；后台管理仍继续使用当前 Express 项目。

GET /image/api/random#

随机返回一张图片。默认 302 跳转到真实图片文件的绝对 URL，适合 CDN 缓存 /image/images/... 下的图片资源；随机入口本身不缓存。图片 API 和最终静态图片响应都会带 Access-Control-Allow-Origin: *，方便主题、前端页面和跨域图片加载使用。

device 优先级高于 type。例如 /image/api/random?device=mobile&type=mobile 会按 device=mobile 选择手机竖屏图片，并使用默认 302 跳转返回；未知 type 会被忽略并按默认 redirect 处理。

返回格式说明：

默认访问 /image/api/random 等价于 /image/api/random?type=redirect。如需直接返回图片本体，可使用 ?type=image；如需 JSON，可使用 ?type=json；如需显式跳转，可使用 ?type=redirect。

缓存与跨域：

• /image/api/... 响应统一设置 Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
• /image/images/... 静态图片统一设置 Cache-Control: public, max-age=31536000, immutable
• 图片 API、302 响应和静态图片响应统一带 Access-Control-Allow-Origin: *

JSON 响应示例：

1
{
2
  "url": "https://example.com/image/images/anime/pc/001.webp",
3
  "gallery": "anime",
4
  "device": "pc",
5
  "filename": "001.webp",
6
  "size": 123456,
7
  "width": 1920,
8
  "height": 1080,
9
  "type": "webp",
10
  "total": 12
11
}

图片管理#

• 支持格式：jpg, jpeg, png, webp, gif, avif
• 上传时自动识别真实格式，扩展名错误也会纠正
• 图库名仅支持小写字母、数字、下划线、短横线
• 也可直接把图片放入 public/images/{gallery}/pc 或 mobile 目录，程序会自动扫描