LibreDomains: Instructions file for Claude Code

LibreDomains - AI 项目上下文

本文档专为 AI 助手提供项目技术上下文，包含架构、工作流程、API 参考等技术细节。

项目概述

LibreDomains 是一个基于 GitHub 的二级域名分发服务，用户通过提交 Pull Request 申请和管理域名。

技术栈：

• Python 3.x - 验证和部署脚本
• GitHub Actions - 自动化 CI/CD
• Cloudflare API - DNS 记录管理
• Git/GitHub - 配置存储和版本控制

项目架构

系统架构图

┌─────────────┐       ┌──────────────┐       ┌───────────────┐
│ GitHub 用户 │──────▶│ Pull Request │──────▶│ 验证检查脚本  │
└─────────────┘       └──────────────┘       └───────┬───────┘
                                                    │
                                                    ▼
┌─────────────┐       ┌──────────────┐       ┌───────────────┐
│ DNS 记录生效 │◀─────│ Cloudflare   │◀─────│ 部署脚本      │
└─────────────┘       └──────────────┘       └───────────────┘

分层架构

1. 配置存储层：GitHub 仓库存储所有域名配置（JSON 格式）
2. 验证层：Python 脚本 + GitHub Actions 自动验证
3. 部署层：Python 脚本通过 Cloudflare API 部署 DNS 记录
4. 监控层：定期健康检查确保域名正常工作

关键依赖

• 第三方服务商：

  • Cloudflare（DNS 解析）
  • GitHub（代码托管、CI/CD）

• 外部 API：

  • Cloudflare API（DNS 管理）
  • GitHub API（PR 评论）

文件结构

.
├── .github/
│   ├── ISSUE_TEMPLATE/           # Issue 模板
│   └── workflows/                # GitHub Actions 工作流
│       ├── deploy-domains.yml    # 部署域名
│       ├── health-check.yml      # 健康检查
│       ├── validate-domain.yml   # 验证域名申请
│       └── generate-stats.yml    # 生成统计
├── config/
│   └── domains.json              # 全局配置（域名列表、规则）
├── docs/                         # 自动生成的报告和数据
│   ├── stats.json                # 统计数据（自动生成）
│   └── stats_report.md           # 统计报告（自动生成）
├── domains/                      # 域名配置目录
│   ├── ciao.su/                  # ciao.su 域名的子域名配置
│   │   └── *.json                # 每个文件代表一个子域名
│   └── ciallo.de/                # ciallo.de 域名的子域名配置
├── scripts/                      # 所有脚本
│   ├── admin/                    # 管理员工具
│   ├── bot/                      # PR 机器人
│   │   └── pr_checker.py         # 检查 PR 中的域名申请
│   ├── cloudflare/               # Cloudflare 集成
│   │   └── cloudflare_manager.py # DNS 记录管理
│   ├── dns/                      # DNS 工具
│   ├── health/                   # 健康检查
│   │   └── domain_health.py      # 域名健康检查
│   ├── stats/                    # 统计脚本
│   │   └── domain_stats.py       # 生成域名统计
│   ├── utils/                    # 工具函数
│   └── validation/               # 验证逻辑
│       └── domain_validator.py   # 域名配置验证器
├── CLAUDE.md                     # 本文件（AI 项目上下文）
├── GUIDE.md                      # 用户和管理员完整指南
├── README.md                     # 项目主页
├── TERMS_OF_SERVICE.md           # 服务条款
└── requirements.txt              # Python 依赖