Mochi API - 麻薯动态数据服务

麻薯 Mochi 活动追踪与统计 API，为前端页面提供动态数据展示能力。

快速开始

# 安装依赖
pip install -r requirements.txt

# 复制配置文件
cp .env.example .env
# 编辑 .env 填入 CNB_TOKEN（可选，不填则使用示例数据）

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8901

# 访问 API 文档
# Swagger UI: http://localhost:8901/docs
# ReDoc:       http://localhost:8901/redoc

API 端点

端点	方法	说明
/	GET	服务信息
/health	GET	健康检查
/api/activities	GET	活动日志列表
/api/stats	GET	数据统计

活动日志 API

GET /api/activities?limit=20&type=代码提交

参数：

• limit (int, 可选): 返回条数，默认 20，范围 1-100
• type (string, 可选): 活动类型过滤

活动类型：

• 代码提交 - 代码推送
• PR合并 - Pull Request 合并
• 仓库创建 - 新仓库创建
• Issue处理 - Issue 创建/关闭
• 发文 - 博客/文章发布

响应示例：

{
  "activities": [
    {
      "time": "2025-07-11T14:30:00Z",
      "type": "代码提交",
      "description": "提交 feat: 新增活动日志 API 模块",
      "link": "https://cnb.cool/cnbnm/mochi-site/-/commit/abc1234"
    }
  ],
  "total": 10
}

数据统计 API

GET /api/stats

响应示例：

{
  "total_repos": 12,
  "public_repos": 8,
  "organizations": 3,
  "monthly_activity": 87,
  "last_activity_time": "2025-07-11T14:30:00Z",
  "server_status": "running",
  "uptime_days": 42,
  "contributors": 5,
  "open_issues": 4,
  "merged_prs_this_month": 15,
  "data_source": "mock",
  "cache_age_seconds": 30
}

数据源

• Mock 模式（默认）：使用内置静态示例数据，无需配置即可运行
• CNB API 模式：在 .env 中配置 CNB_TOKEN 后，自动从 CNB 平台拉取真实数据

切换逻辑：服务启动时自动尝试连接 CNB API，成功则使用真实数据，失败则回退到 mock 数据。

缓存默认 TTL 为 300 秒（5 分钟），可通过 CACHE_TTL_SECONDS 配置。

部署到 175 服务器

# 一键部署
chmod +x deploy/deploy.sh
./deploy/deploy.sh

# 手动管理
sudo systemctl start mochi-api    # 启动
sudo systemctl stop mochi-api     # 停止
sudo systemctl restart mochi-api  # 重启
sudo systemctl status mochi-api   # 状态
journalctl -u mochi-api -f        # 查看日志

项目结构

mochi-site/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── models.py            # Pydantic 数据模型
│   ├── routers/
│   │   ├── activities.py    # 活动日志路由
│   │   └── stats.py         # 统计路由
│   ├── services/
│   │   ├── cache.py         # 缓存服务 & 后台刷新
│   │   └── cnb_client.py    # CNB API 客户端
│   └── data/
│       └── mock_data.py     # 静态示例数据
├── config/
│   └── settings.py          # 应用配置
├── deploy/
│   ├── mochi-api.service    # systemd unit 文件
│   └── deploy.sh            # 部署脚本
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

环境变量

变量	默认值	说明
CNB_API_BASE	https://api.cnb.cool	CNB API 地址
CNB_ORG	cnbnm	组织名
CNB_TOKEN	空	CNB API Token（留空使用 mock 数据）
HOST	0.0.0.0	监听地址
PORT	8901	监听端口
CACHE_TTL_SECONDS	300	缓存刷新间隔（秒）