sub2api 介绍与部署教程

什么是 sub2api？

sub2api 是一个轻量级的订阅转换 API 服务，主要用于将各种订阅格式进行转换和统一管理。它基于 subconverter 核心，提供简单易用的 RESTful API 接口，方便用户快速搭建自己的订阅转换服务。

主要特性

✨ 核心功能

• 多格式支持：支持 Clash、V2Ray、Sing-Box 等多种订阅格式
• RESTful API：简洁的 HTTP 接口，易于集成
• 轻量级部署：资源占用低，适合各种服务器环境
• 自定义规则：支持自定义转换规则和过滤器
• 高兼容性：兼容主流订阅格式和客户端

🎯 适用场景

• 个人订阅管理
• 团队订阅分发
• 多格式订阅转换
• 订阅链接统一管理

部署教程

方式一：Docker 部署（推荐）

1. 准备工作

确保服务器已安装 Docker：

# 检查 Docker 是否安装
docker --version

# 如未安装，执行以下命令
curl -fsSL https://get.docker.com | bash

2. 拉取镜像

docker pull tindy2013/sub2api:latest

3. 创建配置目录

mkdir -p /opt/sub2api/config
mkdir -p /opt/sub2api/logs

4. 启动容器

docker run -d \
  --name sub2api \
  -p 8080:8080 \
  -v /opt/sub2api/config:/app/config \
  -v /opt/sub2api/logs:/app/logs \
  --restart always \
  tindy2013/sub2api:latest

参数说明：

• -p 8080:8080：映射端口（可根据需要修改）
• -v：挂载配置和日志目录
• --restart always：容器自动重启

5. 验证部署

# 查看容器状态
docker ps | grep sub2api

# 测试 API 是否正常
curl http://localhost:8080/health

返回 {"status":"ok"} 表示部署成功。

方式二：源码部署

1. 克隆项目

git clone https://github.com/tindy2013/sub2api.git
cd sub2api

2. 安装依赖

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

3. 配置文件

编辑 config/config.yaml：

server:
  port: 8080
  host: 0.0.0.0

subconverter:
  path: /path/to/subconverter

log:
  level: info
  file: logs/app.log

4. 启动服务

# 前台运行
python main.py

# 后台运行（推荐）
nohup python main.py > logs/app.log 2>&1 &

5. 使用 systemd 管理服务

创建服务文件 /etc/systemd/system/sub2api.service：

[Unit]
Description=sub2api Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/sub2api
ExecStart=/usr/bin/python3 main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

systemctl daemon-reload
systemctl enable sub2api
systemctl start sub2api
systemctl status sub2api

API 使用示例

1. 健康检查

curl http://your-server:8080/health

2. 订阅转换

curl -X POST http://your-server:8080/convert \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/subscription",
    "target": "clash",
    "rules": "default"
  }'

3. 获取支持的目标格式

curl http://your-server:8080/targets

配置说明

环境变量配置

高级配置

编辑 config/config.yaml 可配置：

• 转换规则：自定义订阅转换规则
• 过滤器：节点筛选和过滤
• 缓存设置：API 响应缓存策略
• 速率限制：防止 API 滥用

常见问题

Q1: 启动失败，端口被占用

解决方案：

# 查看占用端口的进程
lsof -i :8080

# 修改配置中的端口或终止占用进程
kill -9 <PID>

Q2: Docker 容器无法启动

解决方案：

# 查看容器日志
docker logs sub2api

# 检查挂载目录权限
chmod -R 755 /opt/sub2api

Q3: 转换失败或返回空结果

解决方案：

• 检查源订阅链接是否有效
• 确认目标格式支持
• 查看日志文件排查错误

安全建议

1. 使用 HTTPS：通过 Nginx 反向代理配置 SSL
2. 添加认证：配置 API Token 或 Basic Auth
3. 限制访问：使用防火墙限制访问 IP
4. 定期更新：保持镜像/代码为最新版本

Nginx 反向代理配置示例

server {
    listen 443 ssl;
    server_name sub2api.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

性能优化

1. 启用缓存

cache:
  enabled: true
  ttl: 3600  # 缓存 1 小时

2. 配置 CDN

对于高并发场景，可在前端配置 CDN 加速。

3. 负载均衡

多实例部署时，使用 Nginx 或 HAProxy 进行负载均衡。

监控与维护

日志查看

# Docker 方式
docker logs -f sub2api

# 源码部署
tail -f logs/app.log

健康检查脚本

#!/bin/bash
RESPONSE=$(curl -s http://localhost:8080/health)
if [[ $RESPONSE == *'"status":"ok"'* ]]; then
    echo "Service is healthy"
    exit 0
else
    echo "Service is down"
    exit 1
fi

总结

sub2api 是一个强大且易用的订阅转换 API 服务，通过简单的部署即可实现：

• ✅ 多格式订阅统一管理
• ✅ 灵活的转换规则
• ✅ 轻量级资源占用
• ✅ 易于维护和扩展

无论是个人使用还是团队部署，sub2api 都是一个值得考虑的选择。

项目地址：https://github.com/tindy2013/sub2api
文档：参考官方 GitHub 仓库
社区支持：欢迎提交 Issue 和 PR

希望本教程对你有所帮助！如有问题，欢迎在评论区留言讨论。