5 分钟跑通 aniwatch-api: 本地部署 + Docker 一键启动完整教程
5 分钟跑通 aniwatch-api: 本地部署 + Docker 一键启动完整教程
aniwatch-api 是一个基于 Node.js 和 TypeScript 编写的免费动漫数据 RESTful API 服务,它能从 hianimez.to 抓取动漫搜索、剧集列表、播放源等结构化数据。本文将带你用 本地部署 和 Docker 一键启动 两种方式快速跑通 aniwatch-api,新手也能 5 分钟完成部署。
🎯 一分钟了解 aniwatch-api
aniwatch-api 本质是一个"动漫数据接口中间层":它利用 aniwatch 抓取包(底层使用 Cheerio + Axios)解析动漫网站页面,再通过 Hono 框架暴露出一组标准 JSON 接口,供你自己的前端、App 或脚本调用。
核心能力一览:
| 功能 | 接口路径 | 说明 |
|---|---|---|
| 首页数据 | /api/v2/hianime/home |
最新剧集、排行榜、热门/收藏榜 |
| A-Z 列表 | /api/v2/hianime/azlist/{sortOption} |
按首字母分页浏览动漫 |
| 搜索 | /api/v2/hianime/search?q={query} |
支持类型、地区、日期等多维筛选 |
| 动漫详情 | /api/v2/hianime/anime/{animeId} |
简介、声优、相关/推荐动漫 |
| 剧集列表 | /api/v2/hianime/anime/{animeId}/episodes |
全部集数与 filler 标记 |
| 播放源 | /api/v2/hianime/episode/sources |
返回 m3u8 流地址与字幕 |
路由实现集中在 src/routes/hianime.ts,服务入口与端口配置在 src/server.ts,每个接口都内置了缓存与日志中间件。
🖥️ 方式一:本地 3 步部署
前置要求:Node.js 22(与 Dockerfile 中使用的
node:22-alpine保持一致)。
步骤 1:克隆仓库
git clone https://gitcode.com/gh_mirrors/an/aniwatch-api
cd aniwatch-api
步骤 2:安装依赖
npm install
依赖清单见 package.json,核心框架为 hono + @hono/node-server,另有 pino(日志)、ioredis(可选缓存)、envalid(环境变量校验)。
步骤 3:编译并启动
npm run build # 将 TypeScript 编译到 dist/
npm start # 启动服务
💡 开发调试可直接使用
npm run dev(基于 tsx 热重载),省去手动编译。
终端出现 aniwatch-api RUNNING at http://localhost:4000 即部署成功。
✅ 验证接口是否可用
curl http://localhost:4000/health
# 输出: daijoubu
curl http://localhost:4000/v
# 输出: 服务版本号
再请求一个真实数据接口试试(返回首页聚合数据):
curl http://localhost:4000/api/v2/hianime/home
/health 与 /v 两个自检端点定义在 src/server.ts#L48-L54;浏览器直接访问 http://localhost:4000 还能看到项目自带的静态页面(来自 public/ 目录)。
🐳 方式二:Docker 一键启动
Docker 方式省去 Node 环境配置,适合服务器长期运行。
本地构建并运行镜像
docker build -t aniwatch-api .
docker run -d --name aniwatch-api -p 4000:4000 aniwatch-api
运行后同样访问 http://localhost:4000。参数说明:
-d:后台(分离模式)运行容器;--name:为容器命名,方便后续管理;-p 4000:4000:端口映射,想换端口改成-p 8080:4000即可。
📦 Dockerfile 采用了工程化设计:双阶段构建(build 阶段编译 TS,prod 阶段只拷贝产物)、以非特权用户 zoro 运行、内置 HEALTHCHECK 健康检查(每 30 秒执行一次 package.json 中的 healthcheck 脚本),详见 Dockerfile#L50-L56。
⚙️ 常用环境变量配置
在项目根目录复制 .env.example 为 .env 即可自定义配置,所有变量均由 src/config/env.ts 用 envalid 统一校验:
| 变量名 | 默认值 | 作用 |
|---|---|---|
ANIWATCH_API_PORT |
4000 |
服务端口 |
ANIWATCH_API_DEPLOYMENT_ENV |
nodejs |
部署环境(docker/vercel/render 等) |
ANIWATCH_API_MAX_REQS |
生产 6 / 开发 600 |
限流窗口内最大请求数 |
ANIWATCH_API_WINDOW_MS |
生产 30 分钟 | 限流统计时长(毫秒) |
ANIWATCH_API_HOSTNAME |
不设置 | 设置后才启用限流,填你的实例域名 |
ANIWATCH_API_CORS_ALLOWED_ORIGINS |
不限制 | 允许跨域的源,逗号分隔 |
ANIWATCH_API_REDIS_CONN_URL |
不启用 | 可选,配置后启用 Redis 响应缓存 |
完整说明参考 .env.example 中的注释。
🩺 常见问题排查
| 现象 | 原因与解决 |
|---|---|
Cannot find module 'dist/src/server.js' |
忘记编译,先执行 npm run build |
| 端口被占用 | 修改 .env 中 ANIWATCH_API_PORT,Docker 则改 -p 参数 |
| 请求返回 429 | 触发了限流,调大 ANIWATCH_API_MAX_REQS 或取消 ANIWATCH_API_HOSTNAME |
| Redis 连接报错 | 未使用缓存请留空 ANIWATCH_API_REDIS_CONN_URL,不要填无效地址 |
📚 延伸学习
- 接口完整文档与响应结构:README.md
- 限流 / 跨域 / 缓存配置源码:src/config/ratelimit.ts、src/config/cors.ts、src/middleware/cache.ts
- 14 个接口的 Vitest 测试:tests/
- 云部署参考配置:vercel.json、render.yaml
- 贡献指南:CONTRIBUTING.md、更新日志 CHANGELOG.md
部署完成后,你就可以基于这些 JSON 接口开发属于自己的动漫搜索、追番提醒或播放聚合应用了。祝开发愉快! 🚀
