{"id":50463988,"url":"https://github.com/soulteary/gorge-db-api","last_synced_at":"2026-06-01T06:04:11.801Z","repository":{"id":344538066,"uuid":"1182142516","full_name":"soulteary/gorge-db-api","owner":"soulteary","description":"Go Database Management API Service provides Phorge-compatible database-infrastructure HTTP APIs for Phorge.","archived":false,"fork":false,"pushed_at":"2026-03-15T16:43:35.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T16:48:11.540Z","etag":null,"topics":["groge","phabricator","phorge"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soulteary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T05:05:29.000Z","updated_at":"2026-03-15T16:43:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/soulteary/gorge-db-api","commit_stats":null,"previous_names":["soulteary/gorge-db-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/soulteary/gorge-db-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fgorge-db-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fgorge-db-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fgorge-db-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fgorge-db-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soulteary","download_url":"https://codeload.github.com/soulteary/gorge-db-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulteary%2Fgorge-db-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33762215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["groge","phabricator","phorge"],"created_at":"2026-06-01T06:04:11.320Z","updated_at":"2026-06-01T06:04:11.796Z","avatar_url":"https://github.com/soulteary.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gorge-db-api\n\nGo 数据库管理 API 服务，为 Phorge 提供 Phorge 兼容的数据库基础设施 HTTP API。实现了与 Phorge PHP 端相同的数据库集群管理能力，包括健康探测、Schema 差异检查、安装检查和迁移状态查询。\n\n## 特性\n\n- 数据库集群健康探测，支持主从复制状态检查和延迟监控\n- Schema 差异检查，从 INFORMATION_SCHEMA 构建层级化 Schema 树\n- 数据库安装检查，验证 MySQL 版本、引擎、配置参数和时钟同步\n- 迁移状态查询，读取 patch_status 表比对已应用和缺失的 patch\n- 主从路由与读写分离，连接级只读保护\n- 嵌套事务支持，通过 MySQL savepoint 实现\n- 连接重试与故障转移，master 不可用时自动 fallback 到 replica\n- 双重配置模式：Phorge 原生 JSON 配置和独立环境变量\n- 统一 Phorge Conduit 兼容的 JSON 响应格式\n- 静态编译，Docker 镜像极轻量\n- 内置健康检查端点，适配容器编排\n\n## 快速开始\n\n### 本地运行\n\n```bash\ngo build -o gorge-db-api ./cmd/server\n./gorge-db-api\n```\n\n服务默认监听 `:8080`。\n\n### Docker 运行\n\n```bash\ndocker build -t gorge-db-api .\ndocker run -p 8080:8080 gorge-db-api\n```\n\n### 带配置运行\n\n```bash\nexport MYSQL_HOST=127.0.0.1\nexport MYSQL_PORT=3306\nexport MYSQL_USER=root\nexport MYSQL_PASS=your_password\nexport SERVICE_TOKEN=your_service_token\nexport STORAGE_NAMESPACE=phorge\n./gorge-db-api\n\n# 或使用 Phorge 配置文件\nexport PHORGE_CONFIG=/path/to/local.json\n./gorge-db-api\n```\n\n## 配置\n\n支持两种配置方式：环境变量（默认）和 Phorge 风格 JSON 配置文件。\n\n### 环境变量\n\n| 变量 | 默认值 | 说明 |\n|---|---|---|\n| `LISTEN_ADDR` | `:8080` | 服务监听地址 |\n| `PHORGE_CONFIG` | (空) | Phorge 风格 JSON 配置文件路径，设置后从文件加载配置 |\n| `MYSQL_HOST` | `127.0.0.1` | MySQL 主机地址 |\n| `MYSQL_PORT` | `3306` | MySQL 端口 |\n| `MYSQL_USER` | `root` | MySQL 用户名 |\n| `MYSQL_PASS` | (空) | MySQL 密码 |\n| `STORAGE_NAMESPACE` | `phorge` | 存储命名空间，用作数据库名前缀 |\n| `SERVICE_TOKEN` | (空) | API 认证 Token，通过 `X-Service-Token` 请求头传递 |\n\n### JSON 配置文件\n\n当设置 `PHORGE_CONFIG` 时，从指定的 JSON 文件加载配置：\n\n```json\n{\n  \"mysql.host\": \"127.0.0.1\",\n  \"mysql.port\": 3306,\n  \"mysql.user\": \"root\",\n  \"mysql.pass\": \"password\",\n  \"storage.default-namespace\": \"phorge\",\n  \"cluster.databases\": [\n    {\n      \"host\": \"master1\",\n      \"port\": 3306,\n      \"role\": \"master\",\n      \"partition\": [\"default\"]\n    },\n    {\n      \"host\": \"replica1\",\n      \"port\": 3306,\n      \"role\": \"replica\"\n    }\n  ]\n}\n```\n\n## API\n\n所有 `/api/db/*` 端点在配置 `SERVICE_TOKEN` 时需要认证。认证方式：\n\n- 请求头：`X-Service-Token: \u003ctoken\u003e`\n- 查询参数：`?token=\u003ctoken\u003e`\n\n### GET /api/db/servers\n\n列出所有数据库节点及健康状态。\n\n**响应** (200)：\n\n```json\n{\n  \"data\": [\n    {\n      \"host\": \"127.0.0.1\",\n      \"port\": 3306,\n      \"is_master\": true,\n      \"connection_status\": \"okay\",\n      \"connection_latency_sec\": 0.003,\n      \"replica_status\": \"okay\"\n    }\n  ]\n}\n```\n\n### GET /api/db/servers/:ref/health\n\n指定节点健康详情。`:ref` 为节点标识，格式为 `host:port`。\n\n### GET /api/db/schema-diff\n\n从 INFORMATION_SCHEMA 获取 Schema 树结构。\n\n### GET /api/db/schema-issues\n\n扁平化的 Schema 问题列表。\n\n### GET /api/db/setup-issues\n\n数据库安装配置检查结果。\n\n### GET /api/db/charset-info\n\n各节点字符集信息。\n\n### GET /api/db/migrations/status\n\n迁移 patch 应用状态。\n\n### GET /healthz\n\n健康检查端点，不需要认证。\n\n**响应** (200)：\n\n```json\n{\"status\": \"ok\"}\n```\n\n### 错误响应\n\n所有错误响应使用统一的 JSON 格式：\n\n```json\n{\n  \"error\": {\n    \"code\": \"ERR_QUERY\",\n    \"message\": \"connect failed after 3 attempts: ...\"\n  }\n}\n```\n\n| 错误码 | HTTP 状态码 | 含义 |\n|---|---|---|\n| `ERR_UNAUTHORIZED` | 401 | Service Token 缺失 |\n| `ERR_READONLY_WRITE` | 409 | 对只读连接发起写操作 |\n| `ERR_MASTER_UNREACHABLE` | 503 | Master 节点不可达 |\n| `ERR_ALL_UNREACHABLE` | 503 | 所有节点不可达 |\n| `ERR_ACCESS_DENIED` | 403 | 数据库访问被拒绝 |\n| `ERR_CONNECTION_LOST` | 500 | 数据库连接丢失 |\n| `ERR_QUERY` | 500 | 查询执行失败 |\n\n## 项目结构\n\n```\ngorge-db-api/\n├── cmd/server/main.go              # 服务入口\n├── internal/\n│   ├── cluster/\n│   │   ├── config.go               # 集群配置加载（JSON 文件 / 环境变量）\n│   │   ├── ref.go                  # DatabaseRef 节点模型与状态常量\n│   │   ├── router.go               # 主从路由与连接缓存\n│   │   └── health.go               # 健康探测与复制状态检查\n│   ├── dbcore/\n│   │   ├── conn.go                 # 数据库连接池与读写保护\n│   │   ├── query.go                # 只读查询正则判定\n│   │   ├── retry.go                # 连接与查询重试策略\n│   │   └── tx.go                   # 嵌套事务管理（savepoint）\n│   ├── schema/\n│   │   ├── schema.go               # Schema 差异与字符集检查\n│   │   ├── setup.go                # 安装配置检查\n│   │   └── migration.go            # 迁移状态查询\n│   ├── compat/\n│   │   ├── response.go             # 统一 API 响应结构\n│   │   └── errors.go               # 错误码体系与 MySQL 错误映射\n│   └── httpapi/\n│       └── handlers.go             # HTTP 路由注册、认证中间件与处理器\n├── scripts/\n│   └── validate.sh                 # 集成验证脚本\n├── Dockerfile                      # 多阶段 Docker 构建\n├── go.mod\n└── go.sum\n```\n\n## 开发\n\n```bash\n# 运行全部测试\ngo test ./...\n\n# 运行测试（带详细输出）\ngo test -v ./...\n\n# 构建二进制\ngo build -o gorge-db-api ./cmd/server\n\n# 集成验证（需要运行中的服务和 MySQL）\n./scripts/validate.sh http://localhost:8080 your_service_token\n```\n\n## 技术栈\n\n- **语言**：Go 1.26\n- **HTTP 框架**：[Echo](https://echo.labstack.com/) v4.15.1\n- **数据库驱动**：[go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) v1.9.3\n- **许可证**：Apache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulteary%2Fgorge-db-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoulteary%2Fgorge-db-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulteary%2Fgorge-db-api/lists"}