5 分钟跑通 aniwatch-api: 本地部署 + Docker 一键启动完整教程

原创2026-11-14 22:44:482,255 阅读

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 或脚本调用。

aniwatch-api 动漫数据接口服务示例:和风动漫场景图

核心能力一览:

功能 接口路径 说明
首页数据 /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,不要填无效地址

📚 延伸学习

部署完成后,你就可以基于这些 JSON 接口开发属于自己的动漫搜索、追番提醒或播放聚合应用了。祝开发愉快! 🚀

登录后查看全文
aniwatch-api