SubProxy

一个基于 Koa + React 的现代订阅代理管理系统，支持 Docker 部署和数据持久化。可用于个人或团队使用，统一管理和分享订阅代理。

✨ 功能特性

🎯 核心功能

订阅管理：创建、编辑、删除、启用/禁用订阅
置顶功能：支持最多3个订阅置顶，固定显示在列表顶部
搜索筛选：按名称、状态、流量类型、有效期筛选，支持实时搜索
数据统计：实时显示订阅统计信息，包括总数、启用数、无限流量数等
用户认证：安全的JWT登录系统，支持密码重置
个人中心：头像上传、个人信息管理、账户设置
数据备份：支持数据导入导出，自动备份保护

🔧 技术特性

现代化UI：基于 Ant Design 的管理界面，响应式设计
数据持久化：Docker 数据卷映射，支持升级不丢失数据
默认数据：预设订阅配置和管理员账户，开箱即用
头像保护：默认头像文件受保护，上传新头像不会删除默认头像
智能配置：自动检测环境，智能配置 baseUrl
类型安全：TypeScript 全栈开发，共享类型定义
Monorepo：统一管理前后端代码，支持独立构建和部署

🚀 快速开始

环境要求

Docker & Docker Compose
Node.js 18+ (开发环境)
支持 Clash、Shadowrocket 等代理客户端

📱 支持的客户端

Clash: Clash for Windows, ClashX, Clash Verge
Shadowrocket: iOS 设备
其他: 支持标准订阅链接格式的客户端

一键部署

# 克隆项目
git clone https://github.com/qinhua/sub-proxy.git
cd sub-proxy

# 使用 Docker Compose 部署
docker-compose up -d

# 或使用 Docker 命令部署（数据卷根据情况自己修改）
docker run -d \
  --name sub-proxy-app \
  --restart unless-stopped \
  -p 3001:3001 \
  -v /opt/sub-proxy/data:/app/server/data \
  -v /opt/sub-proxy/upload:/app/server/upload \
  -v /opt/sub-proxy/logs:/app/logs \
  marekqin/sub-proxy:latest
/bin/sh -c ./start.sh

访问系统

管理界面：http://[你的IP]:3001
默认账号：admin
默认密码：admin123456

📁 项目结构

sub-proxy/
├── server/                    # 后端服务 (Koa.js)
│   ├── src/                   # 源代码
│   │   ├── index.ts           # 服务入口
│   │   ├── routes.ts          # API 路由
│   │   ├── authRoutes.ts      # 认证路由
│   │   ├── db.ts              # 数据库管理
│   │   ├── auth.ts            # 认证逻辑
│   │   └── types.ts           # 类型定义
│   ├── data/                  # 数据文件
│   │   └── db_default.json    # 默认数据模板
│   └── upload/                 # 上传文件目录
│       └── avatar/             # 头像文件
├── web/                       # 前端应用 (React + Vite)
│   ├── src/                   # 源代码
│   │   ├── App.tsx            # 主应用组件
│   │   ├── pages/             # 页面组件
│   │   │   ├── Login.tsx      # 登录页面
│   │   │   ├── SubscriptionList.tsx    # 订阅列表
│   │   │   ├── SubscriptionForm.tsx    # 订阅表单
│   │   │   └── Settings.tsx   # 设置页面
│   │   ├── contexts/          # React 上下文
│   │   ├── utils/             # 工具函数
│   │   └── types.ts           # 类型定义
│   └── dist/                  # 构建输出
├── shared/                    # 共享代码
│   └── types/                 # 共享类型定义
├── docs/                      # 项目文档
├── data/                      # 运行时数据（Docker 映射）
├── upload/                   # 上传文件（Docker 映射）
├── logs/                      # 日志文件（Docker 映射）
├── backups/                   # 数据备份
├── docker-compose.yml         # Docker Compose 配置
├── Dockerfile                 # Docker 镜像构建
├── start.sh                   # Docker 启动脚本
├── reset-password.sh          # 密码重置脚本
└── push-to-dockerhub.sh       # DockerHub 推送脚本

🎯 功能演示

📊 管理界面

仪表板: 实时统计订阅数据，一目了然
订阅列表: 支持置顶、搜索、筛选，操作便捷
订阅编辑: 可视化表单，支持无限流量和永久有效设置
个人中心: 头像上传、信息管理、密码修改

🔧 管理功能

数据备份: 一键导出/导入，保护数据安全
密码重置: 忘记密码时快速恢复，保留所有数据
置顶管理: 重要订阅置顶显示，最多支持3个
实时搜索: 输入即搜索，支持多条件筛选

📱 客户端支持

订阅链接: 标准格式，兼容主流客户端
动态更新: 实时同步订阅状态和配置
多端同步: 一处修改，处处生效

🛠️ 开发环境

本地开发

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建项目
pnpm build

📦 部署方式

1. Docker Compose 部署（推荐）

# 启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

2. 软路由/NAS部署

详见部署文档

💾 数据管理

备份数据

# 手动备份数据
tar -czf subproxy_backup_$(date +%Y%m%d_%H%M%S).tar.gz data/ upload/ logs/

恢复数据

# 停止服务
docker-compose down

# 恢复数据
tar -xzf subproxy_backup_20241201_120000.tar.gz

# 重启服务
docker-compose up -d

重置数据

# 停止服务
docker-compose down

# 备份当前数据
cp -r data data.backup

# 删除数据目录
rm -rf data/* upload/* logs/*

# 重启服务（将自动加载默认数据）
docker-compose up -d

🔧 配置说明

数据持久化

Docker 内部路径	宿主机路径	说明	持久化
`/app/server/data/`	`./data/`	运行时数据库	✅
`/app/server/upload/`	`./upload/`	用户上传文件	✅
`/app/logs/`	`./logs/`	日志文件	✅
`/app/server/data/db_default.json`	不映射	默认数据模板	❌

📚 文档

完整部署指南 - 包含所有部署、数据管理、密码重置等完整指南
DockerHub 推送 - DockerHub 镜像推送指南

🔄 升级流程

1. 备份数据

tar -czf subproxy_backup_$(date +%Y%m%d_%H%M%S).tar.gz data/ upload/ logs/

2. 停止服务

docker-compose down

3. 更新代码

git pull

4. 重新部署

docker-compose up -d

5. 验证数据

# 检查服务状态
docker-compose ps

# 检查数据
ls -la data/ upload/ logs/

🛡️ 安全说明

默认管理员密码：admin123456
建议首次登录后立即修改密码
生产环境请使用强密码
定期备份重要数据

🔑 密码重置

如果忘记密码，可以使用以下命令重置（保留所有订阅和设置）：

# 使用脚本重置（推荐）
./reset-password.sh <容器名称>

# 或使用Docker命令
docker exec <容器名称> sh -c "cp /app/server/data/db.json /app/server/data/db_backup_$(date +%Y%m%d_%H%M%S).json && node -e \"const fs=require('fs'); const db=JSON.parse(fs.readFileSync('/app/server/data/db.json','utf8')); db.users=[{id:'admin-001',username:'admin',password:'\\\$2b\\\$10\\\$0jOBh3OCJN4BeVCBPM8hTO3cHzCvhFRcuJpDm30k5ht1uJ.mozthK',createdAt:'2025-10-24T16:35:18.920Z',lastLoginAt:null,avatar:'/upload/avatar/default_avatar.png',email:'',phone:'',lastUpdatedAt:new Date().toISOString()}]; fs.writeFileSync('/app/server/data/db.json',JSON.stringify(db,null,2));\" && echo '✅ 密码重置成功！保留所有订阅和设置。默认用户名: admin, 密码: admin123456'"

重置后默认登录信息：

用户名: admin
密码: admin123456

🐛 故障排除

常见问题

容器无法启动

# 查看详细日志
docker-compose logs

# 检查数据目录权限
chmod -R 755 data upload logs

# 检查端口占用
netstat -tlnp | grep 3001

数据丢失

# 从备份恢复
tar -xzf subproxy_backup_20241201_120000.tar.gz

# 重置为默认数据
docker-compose down
rm -rf data/* upload/* logs/*
docker-compose up -d

端口冲突

# 修改 docker-compose.yml 中的端口映射
ports:
  - "3002:3001"  # 使用不同端口

忘记密码

# 使用密码重置脚本
./reset-password.sh <容器名称>

无法访问服务

# 检查防火墙设置
iptables -L | grep 3001

# 检查容器状态
docker ps | grep sub-proxy

# 检查健康状态
curl http://localhost:3001/health

日志查看

# 查看服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f sub-proxy

# 查看容器日志
docker logs <容器名称>

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

Fork 项目 到你的 GitHub 账户
创建分支 git checkout -b feature/your-feature
提交更改 git commit -m 'Add some feature'
推送分支 git push origin feature/your-feature
提交 Pull Request

开发规范

使用 TypeScript 进行类型安全开发
遵循 ESLint 和 Prettier 代码规范
添加适当的注释和文档
确保测试通过

TODO

支持订阅转换功能
支持外挂第三方订阅
支持配置文件正确性检测

📞 支持

如果遇到问题，请：

查看故障排除部分
检查文档目录
搜索 Issues 看是否有类似问题
提交新 Issue 描述问题

社区

GitHub: qinhua/sub-proxy
Issues: 问题反馈
Discussions: 讨论区

SubProxy - 让订阅管理更简单！

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
docs		docs
server		server
shared/types		shared/types
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
push-to-dockerhub.sh		push-to-dockerhub.sh
reset-password.sh		reset-password.sh
start.sh		start.sh

License

qinhua/sub-proxy

Folders and files

Latest commit

History

Repository files navigation