# api-server

基于 Go + Gin 的 API 服务平台，将 [sol148-extractor](../sol148-extractor) 的功能封装为 RESTful API，内置统计分析监控和嵌入式视频浏览前端。

---

## 三层架构

```
┌─────────────────────────────────────────────────────────────┐
│                    前端（嵌入式 SPA）                         │
│  /              运维仪表盘（Chart.js 暗色主题）                │
│  /video         视频网站（浏览/搜索/提取/作者/分类）            │
├─────────────────────────────────────────────────────────────┤
│                  核心业务 API（sol148-extractor 功能）        │
│  POST /api/extract         视频源提取                        │
│  POST /api/extract/batch   批量提取（并发可控）                │
│  GET  /api/categories      分类目录                          │
│  GET  /api/category/:code  分类视频列表（分页/全量）           │
│  GET  /api/author/:uid     作者视频列表（分页/全量）           │
├─────────────────────────────────────────────────────────────┤
│              统计监控 API（运维用，监控业务 API）              │
│  GET  /api/stats/overview      总览                          │
│  GET  /api/stats/requests      时间序列                       │
│  GET  /api/stats/geo           地理分布（ip2region）          │
│  GET  /api/stats/concurrency   并发统计                       │
│  GET  /api/stats/latency       延迟百分位                     │
│  GET  /api/stats/status        状态码分布                     │
│  GET  /api/stats/endpoints     热门端点                       │
│  GET  /api/stats/top-ips       高频 IP                        │
│  GET  /api/stats/realtime      实时统计                       │
├─────────────────────────────────────────────────────────────┤
│                 内部引擎（Go 原生实现）                        │
│  scraper/     Session 预热 + 正则提取（Python → Go 移植）     │
│  analytics/   线程安全统计引擎 + ip2region                     │
│  middleware/  Gin 中间件自动采集请求                            │
└─────────────────────────────────────────────────────────────┘
```

---

## 项目结构

```
api-server/
├── main.go                             # CLI 入口
├── cmd/
│   ├── root.go                         # cobra 根命令 + viper
│   └── serve.go                        # serve 子命令
├── internal/
│   ├── scraper/                        # 核心提取引擎（sol148-extractor 的 Go 移植）
│   │   ├── session.go                  # HTTP Session 预热（反爬 Cookie）
│   │   ├── extractor.go                # 视频源提取（strencode2 → unescape → mp4）
│   │   ├── author.go                   # 作者视频列表提取
│   │   └── category.go                 # 分类视频列表提取
│   ├── handler/
│   │   ├── extract.go                  # POST /api/extract, /api/extract/batch
│   │   ├── content.go                  # GET /api/categories, /category/:code, /author/:uid
│   │   ├── stats.go                    # GET /api/stats/*
│   │   └── handler.go                  # /api/health, /api/ping
│   ├── analytics/
│   │   ├── engine.go                   # 线程安全统计引擎
│   │   └── geoip.go                    # ip2region 地理位置
│   ├── middleware/analytics.go         # Gin 中间件（请求采集）
│   ├── config/config.go                # 配置管理
│   ├── model/stats.go                  # 数据模型
│   └── server/server.go               # 路由注册 + 嵌入式前端
├── web/
│   ├── embed.go                        # //go:embed 嵌入
│   └── static/
│       ├── index.html + app.js + style.css    # 运维仪表盘
│       └── videoapp/
│           ├── index.html              # 视频网站 SPA
│           ├── app.js                  # 路由/API 调用/渲染
│           └── style.css               # 视频站主题
├── data/                               # ip2region.xdb 数据库
└── go.mod
```

---

## 核心业务 API

### 视频源提取

```bash
# 单个提取
curl -X POST http://localhost:8080/api/extract \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://h1014.sol148.com/view_video.php?viewkey=xxx"}'

# 批量提取（并发度可配）
curl -X POST http://localhost:8080/api/extract/batch \
  -H 'Content-Type: application/json' \
  -d '{"urls":["url1","url2","url3"], "concurrency":3}'
```

响应示例：
```json
{
  "code": 0,
  "data": {
    "url": "原始 URL",
    "video_url": "https://cdn.xxx/.../12345.mp4?st=...",
    "video_id": "12345",
    "title": "视频标题",
    "duration": "00:09:29",
    "views": 65979,
    "favorites": 1213,
    "author_name": "作者名",
    "author_url": "https://h1014.sol148.com/uprofile.php?UID=xxx"
  }
}
```

### 分类浏览

```bash
# 分类列表
curl http://localhost:8080/api/categories

# 分类视频（分页）
curl "http://localhost:8080/api/category/rf?page=1&viewtype=basic"

# 全量获取
curl "http://localhost:8080/api/category/top?all=true&max_pages=5"
```

### 作者浏览

```bash
# 作者视频（分页）
curl "http://localhost:8080/api/author/kBBKslfHMfbdEHb5SeiLocPIbBow7t6?page=1"

# 全量获取
curl "http://localhost:8080/api/author/kBBKslfHMfbdEHb5SeiLocPIbBow7t6?all=true"
```

---

## 视频网站前端 (`/video`)

一个完整功能的单页应用，直观展示和测试所有 API：

| 页面 | 路由 | 调用的 API |
|------|------|-----------|
| 首页 | `#/home` | `/categories`, `/stats/overview` |
| 分类浏览 | `#/browse` | `/categories`, `/category/:code` |
| 分类列表 | `#/categories` | `/categories` |
| 视频详情 | `#/watch/:viewkey` | `/extract`, `/category/:code` |
| 作者页 | `#/author/:uid` | `/author/:uid` |
| 搜索 | `#/search` | `/category/:code` (全量 + 前端过滤) |

特色功能：
- 导航栏实时显示 QPS / 活跃连接 / 延迟（来自 `/stats/realtime`）
- 视频详情页自动调用提取 API 获取视频源
- 一键复制视频源地址
- 分类分页浏览
- 客户端搜索过滤
- 暗色主题，响应式布局

---

## 设计对应关系（sol148-extractor → api-server）

| sol148-extractor (Python) | api-server (Go) |
|---------------------------|-----------------|
| `extract.py` — 视频源提取 | `scraper/extractor.go` + `POST /api/extract` |
| `extract_author.py` — 作者列表 | `scraper/author.go` + `GET /api/author/:uid` |
| `crawl_category.py` — 分类列表 | `scraper/category.go` + `GET /api/category/:code` |
| `argparse` CLI | `cobra` + `viper` |
| `requests.Session` 预热 | `scraper/session.go` — HTTP Cookie Jar + 自动预热 |
| `strencode2 → unescape → regex` | Go `url.QueryUnescape` + `regexp` |
| JSON / URL-only 输出 | RESTful JSON API |
| `-i urls.txt -o results.json` | `POST /extract/batch` 并发提取 |
| `--delay` 页间延迟 | HTTP 无状态，按需调用 |

---

## 快速开始

```bash
# 编译
go build -o api-server .

# 启动（无需 ip2region 也可运行）
./api-server serve

# 带 IP 地理位置
./api-server serve --geoip --geoip-db ./data/ip2region.xdb

# 开发模式
./api-server serve --mode debug --port 9090
```

```bash
# 访问
http://localhost:8080/        # 运维仪表盘
http://localhost:8080/video   # 视频网站
```

---

## 技术栈

- **Go 1.22+** — 高性能编译型语言
- **Gin** — HTTP 框架
- **Cobra + Viper** — CLI + 配置
- **ip2region** — IP 地理位置
- **Chart.js** — 前端图表
- **//go:embed** — 资源嵌入