shine09/clash-config-store repository overview

⁠Clash Config Store

Clash Config Store⁠ 是一个面向 Mihomo/Clash 的订阅编排与分发平台：
把多个上游代理订阅、规则集和自定义配置统一管理，最终生成可直接下发的完整 YAML。

⁠这个项目做什么

• 统一管理上游订阅源（Provider），支持缓存、手动刷新、UA 定制
• 提供可复用的「配置模板」「规则集库」「托管规则集」
• 支持可视化编辑自定义配置（proxies / proxy-groups / rules）
• 生成带 Token 的订阅链接（/sub/{token}），支持重新生成与过期控制
• 提供访问限制（IP / CIDR / 国家）和访问日志
• 支持中英文界面、深浅色主题

⁠界面截图

首页	托管规则集

自定义配置 - 代理组	自定义配置 - 规则

订阅管理 - 二维码分享	规则集库

⁠技术栈与结构

• 后端：Go 1.25、Gin、GORM、JWT
• 前端：React + TypeScript + Vite + Tailwind + shadcn/ui
• 数据库：SQLite（默认）或 MySQL/MariaDB
• 部署形态：单后端容器（同时提供 API + 前端静态资源）

目录概览：

cmd/server/main.go         # 程序入口、路由注册
internal/                  # 后端核心代码（handler/service/model 等）
frontend/                  # 前端工程
docker-compose.example.yml # Compose 示例：默认拉取 Docker Hub 镜像，可改为本地构建
Dockerfile                 # 多阶段构建镜像

预构建镜像（Docker Hub，拉取即用）：shine09/clash-config-store⁠

⁠怎么用

⁠1. Docker Compose（推荐）

方式 A：拉取预构建镜像（推荐，启动快）

无需本地构建；确保已安装 Docker Compose⁠。

git clone https://github.com/PrintNow/clash-config-store.git
cd clash-config-store

cp .env.example .env
# 编辑 .env，至少修改 JWT_SECRET

# 首次会拉取 Hub 镜像；./data 挂载为数据目录，首次启动会自动创建 SQLite

docker compose -f docker-compose.example.yml up -d

方式 B：本地构建镜像（更利于审计与可信构建）

克隆仓库后，将示例复制为本地专用文件（勿提交仓库），在副本里注释掉 image、取消注释 build 段，例如：

cp docker-compose.example.yml compose.local.yml
# 编辑 compose.local.yml …

docker compose -f compose.local.yml up -d --build

说明：预构建镜像由发布者维护，生产环境请自行评估信任边界；若更在意供应链安全，优先采用方式 B 在本地或自有 CI 中构建。

默认访问地址：

• Web UI: http://localhost:26406
• API: http://localhost:26406/api
• 公开订阅: http://localhost:26406/sub/<token>

说明：

• 示例 Compose 默认 SQLite（DB_TYPE=sqlite）；image 默认为 shine09/clash-config-store:latest，可按 Docker Hub 标签⁠ 改为固定版本（如 v1.1.0-beta.1）以便复现部署
• 如需外部 MySQL/MariaDB，请在 .env 设置：
  • DB_TYPE=mysql
  • DB_DSN=<mysql dsn>

⁠2. 本地开发运行

后端：

cp .env.example .env
# 编辑 .env，至少修改 JWT_SECRET

go mod tidy
go run ./cmd/server

前端（另开终端）：

cd frontend
npm install
npm run dev

开发访问：

• 前端 Dev Server: http://localhost:5173
• Vite 已内置代理到本地后端（/api、/sub、/ruleset）

⁠核心使用流程

1. 注册并登录账号
2. 在「UA 库」中维护常用 User-Agent（可选）
3. 在「订阅源」中添加上游订阅 URL
4. 在「规则集库 / 托管规则集 / 配置模板 / 自定义配置」中按需建模
5. 在「订阅管理」中新建订阅并绑定来源与配置
6. 复制订阅链接并导入 Mihomo/Clash 客户端

⁠基础二次开发

⁠后端扩展（新增一个资源接口）

建议按现有分层：

1. 在 internal/model 定义模型
2. 在 internal/handler 增加请求处理函数
3. 在 cmd/server/main.go 注册路由
4. 需要时在 internal/service 编排业务逻辑
5. 运行 go test ./... 验证

⁠前端扩展（新增一个页面）

建议流程：

1. 在 frontend/src/pages 新增页面组件
2. 在 frontend/src/api 增加 API 模块
3. 在 frontend/src/components/layout/Sidebar.tsx 添加导航项
4. 在 frontend/src/i18n/locales/zh.ts、frontend/src/i18n/locales/en.ts 补齐文案
5. 运行 cd frontend && npm run build 做类型与构建校验

⁠配置合成相关开发建议

• 订阅下发入口：GET /sub/:token
• 托管规则集入口：GET /ruleset/:token/:name
• 涉及 YAML 生成/规则拼接时，建议同步补充单元测试，避免配置回归

⁠环境变量（常用）

⁠GeoIP（可选）

用于订阅访问场景：按客户端 IP 解析国家/城市，支撑「按国家限制访问」，并在访问日志里记录地理字段。与下发 YAML 里的 GEOIP,CN,DIRECT 等客户端规则不是同一回事。

• 本地 go run：未设置 GEOIP_PATH 且不存在默认路径下的库文件时，地理能力关闭（不影响其它功能）。
• Docker / Compose：构建镜像时会下载并放入 /data/geoip/GeoLite2-City.mmdb，示例里的 GEOIP_PATH 即指向该路径；这与把宿主机 ./data 挂到容器内 /data/store（仅用于 SQLite 数据目录）互不冲突。
• 自建镜像或更新库：make geoip 会把 GeoLite2-City.mmdb 下载到 .docker/geoip/，供 make docker-build 打进镜像；也可自行下载后通过 GEOIP_PATH 指向任意路径。

⁠免责声明

• 本项目仅用于配置管理与技术研究，请遵守你所在地区的法律法规和服务条款。
• 使用者应自行确保订阅来源、规则内容与分发行为具备合法授权；由此产生的法律风险与责任由使用者承担。
• 请勿将本项目用于任何未授权访问、攻击、滥用网络资源或其他违法违规用途。
• 项目默认不提供商业支持、可用性保证或数据完整性担保，生产使用前请自行评估并做好备份、监控与访问控制。