一个高性能、开箱即用的一言（Hitokoto）API后端服务，无需任何配置即可使用。

本项目使用的语句数据来源于 hitokoto-osc/sentences-bundle。

本项目遵循 AGPL-3.0 开源授权，您在使用本项目时需要遵循 AGPL 授权的相关规定。这通常意味着：

• ⚠️ 开源要求: 您在使用、分发、修改、扩充等涉及本项目的操作时您需要开源您的修改作品
• ✅ HTTP API调用: 通过HTTP API调用方式使用不受AGPL传染影响
• 📋 其他使用方式: 除HTTP API调用外，其余使用方式都需要遵循AGPL授权

重要提醒: 如果您直接集成本项目代码或数据到您的应用中，请确保您的应用也遵循AGPL授权要求。

• 🎯 返回标准格式的一言数据 {hitokoto: "内容", from: "来源"}
• 📚 支持12个分类的一言获取
• 🚀 高性能RESTful API，支持>2000 RPS
• 💾 智能缓存，预加载热门分类
• 🔧 开箱即用，无需配置环境变量
• 🛡️ 生产级安全防护和错误处理
• 🐳 Docker容器化部署

1. 创建 docker-compose.yml 文件：

version: '3.8'

services:
  hitokoto-api:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

2. 启动服务：

# 构建并启动
docker-compose up -d

# 测试API
curl http://localhost:3000/api/hitokoto

# 1. 安装依赖
pnpm install

# 2. 启动开发服务
pnpm dev

# 3. 生产集群模式
pnpm start:cluster

GET /api/hitokoto

响应示例：

{
  "hitokoto": "人生如逆旅，我亦是行人。",
  "from": "苏轼"
}

GET /api/hitokoto?c=分类key

分类列表：

• a: 动画 - 1348条
• b: 漫画
• c: 游戏
• d: 文学
• e: 原创 - 1125条
• f: 网络 - 727条
• g: 其他
• h: 影视
• i: 诗词 - 698条
• j: 网易云
• k: 哲学
• l: 抖机灵

GET /api/categories     # 获取分类列表
GET /health            # 健康检查

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 缓存配置
        proxy_cache_valid 200 5m;
        add_header X-Cache-Status $upstream_cache_status;
    }
}

your-domain.com {
    reverse_proxy localhost:3000
    
    # 自动HTTPS
    tls your-email@example.com
    
    # 缓存
    cache {
        ttl 5m
    }
}

在标准配置下（4核CPU，8GB内存）：

• RPS: > 2000 请求/秒
• 响应时间: P95 < 50ms
• 并发支持: > 1000 并发连接
• 内存使用: < 200MB per process
• 预加载数据: 3898条热门句子

# 基础性能测试
pnpm benchmark

# 压力测试
pnpm benchmark:stress

version: '3.8'

services:
  hitokoto-api:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

version: '3.8'

services:
  hitokoto-api:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
    deploy:
      replicas: 2
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

docker run -d -p 3000:3000 --name hitokoto-api your-image-name

├── src/                    # 源代码
│   ├── app.js             # 应用入口
│   ├── routes/            # 路由
│   ├── services/          # 业务逻辑
│   ├── middleware/        # 中间件
│   └── utils/             # 工具类
├── sentences/             # 句子数据
├── categories.json        # 分类配置
├── logs/                  # 日志文件夹（Docker挂载）
├── Dockerfile            # Docker配置
└── ecosystem.config.js   # PM2集群配置

服务使用以下默认配置，无需额外设置：

• 端口: 3000
• 跨域: 允许所有来源（通过反向代理控制）
• 请求限制: 2000次/15分钟
• 缓存时间: 1小时
• 日志级别: info

fetch('http://localhost:3000/api/hitokoto')
  .then(response => response.json())
  .then(data => {
    console.log(data.hitokoto); // 一言内容
    console.log(data.from);     // 来源
  });

import requests

response = requests.get('http://localhost:3000/api/hitokoto')
data = response.json()
print(f"{data['hitokoto']} —— {data['from']}")

curl http://localhost:3000/api/hitokoto

本项目遵循 AGPL-3.0 License。

• 📦 项目整体: 遵循 AGPL-3.0 授权
• 📚 数据来源: 语句数据来源于 hitokoto-osc/sentences-bundle，同样遵循 AGPL-3.0 授权

• ✅ HTTP API调用: 通过HTTP API调用方式使用（推荐，不受AGPL传染影响）
• ⚠️ 代码集成: 直接集成项目代码或数据需要遵循AGPL授权要求
• 📋 修改分发: 任何修改和分发都需要开源并遵循AGPL协议

详细授权条款请参阅 AGPL-3.0 License。

感谢 hitokoto-osc 组织提供的优质语句数据。

---

开箱即用，无需配置，一键部署！ 🚀