# SiteForge Enterprise V8.5.0-dev.1 — P3 认证 API 与安全 MySQL 数据连接器

## 开发范围与实际代码

- **认证 HTTPS JSON API**：原 `v84_api_sources` 数据源升级为 `auth_type` / `auth_header` / `secret_ref`。支持公开、Bearer Token、X-API-Key 和经限制的自定义 `X-*` 请求头。Web 创建数据源时仅校验 `env:SITEFORGE_*` / `file:*` 引用格式；由独立 Worker 执行时才读取凭据。前端、列表和详情响应不返回密钥引用或值。
- **安全 HTTP**：原有 DNS 解析与套接字固定连接、TLS 域名验证继续使用；携带凭据必须走 HTTPS 且禁止重定向，拒绝 Cookie/Host 等非允许的凭据请求头。API JSON 只读 GET，分批暂存，继续支持断点续跑、任务取消、重试及容量限制。
- **MySQL 只读连接器**：新增 `app/connectors_v85.py`；管理员需要在 Worker 环境设置 `SITEFORGE_MYSQL_ALLOWED_HOSTS` 与 `SITEFORGE_MYSQL_ALLOWED_TABLES`，以及数据库侧真实 `SELECT`-only 账号。系统仅接受安全的库名/表名/列名，按唯一游标列执行固定参数化 `SELECT … WHERE key > %s ORDER BY key LIMIT %s`，强制 TLS 证书和主机名校验，开启数据库 READ ONLY 事务。不存在让用户提交原始 SQL 的入口。
- **数据暂存与可审计回滚**：MySQL 单批最多 250 行、最多 50 页且最多 5000 行；API 延续单页 100、总量 5000 的限制。每页用源 ID 和页码建立稳定来源标识；Worker 崩溃后按页/批次检查点恢复；仍需明确点击“提交”后才真正入站。用户可以在允许的条件下用 V8 批次回滚功能撤销导入，防止覆盖人工修改。
- **关系检查**：新增独立只读 API 预览批次的品牌、分类和未知品牌页面引用；只提示问题、不猜测品牌、不修改内容。网站隔离与会话/CSRF 权限继续保留。
- **后台入口**：`/production-v8` 增加认证方式、密钥引用字段、MySQL 数据源、Worker 执行/取消，以及批次“关系检查”按钮。

## 使用与密钥配置

开发环境示例（不要将凭据提交到 Git）：

```dotenv
SITEFORGE_MYSQL_ALLOWED_HOSTS=mysql.example.com
SITEFORGE_MYSQL_ALLOWED_TABLES=catalog.products_public,catalog.brands_public
SITEFORGE_MYSQL_READ_USER=<read_only_username>
SITEFORGE_MYSQL_READ_PASSWORD=<read_only_password>
```

然后数据源配置：

```json
{
  "host":"mysql.example.com",
  "database":"catalog",
  "table":"products_public",
  "key_column":"id",
  "columns":["id","name","brand","category"],
  "user_ref":"env:SITEFORGE_MYSQL_READ_USER",
  "password_ref":"env:SITEFORGE_MYSQL_READ_PASSWORD",
  "mapping":{"title":"name","brand":"brand","category":"category"},
  "page_size":100,
  "max_pages":20
}
```

生产环境推荐将账号/密码分别保存到宿主机 `private_secrets/mysql_reader_user` 和 `private_secrets/mysql_reader_password`，并启用 `compose.mysql-secrets.yaml` 只挂载到 Worker 的 `/run/secrets`。前端对应填写 `file:mysql_reader_user` / `file:mysql_reader_password`。如服务器使用自签名 CA，将受信任 CA 放在 `private_ca/mysql-ca.pem`，并设置 `SITEFORGE_MYSQL_CA_FILE=/etc/siteforge/certs/mysql-ca.pem`。**这两类目录已排除在 Git/Docker 构建上下文之外**。

执行：

```bash
# 确保 private_secrets/ 与 private_ca/ 已创建、权限正确
mkdir -p private_secrets private_ca
docker compose -f compose.yaml -f compose.mysql-secrets.yaml up -d --build
```

外部 API 示例（Bearer）：选择 HTTPS URL、`auth_type=bearer`、`secret_ref=file:partner_api_token`，并将密钥文件放在 Worker 挂载的 `/run/secrets`。密钥不放在 URL 参数、JSON 正文、API 结果或 Git 仓库中。缺少该密钥文件时，Worker 会报告采集失败；并不会降级为公开采集。

## 主要 API

| API | 说明 |
|---|---|
| `POST /api/connectors/sites/{site}/api-sources` | 公开或认证 HTTPS JSON API 数据源 |
| `GET /api/connectors/sites/{site}/api-sources/{id}` | API 进度；不显示密钥引用 |
| `POST /api/connectors/sites/{site}/mysql-sources` | 创建经白名单校验的 MySQL 数据源（owner 权限） |
| `GET /api/connectors/sites/{site}/mysql-sources` | MySQL 数据源列表 |
| `POST /api/connectors/sites/{site}/mysql-sources/{id}/scan` | 进入 Worker 队列 |
| `POST /api/connectors/sites/{site}/mysql-sources/{id}/cancel` | 申请取消 |
| `GET /api/connectors/sites/{site}/import-batches/{id}/relationships` | 预览品牌、分类及潜在缺失关联 |

## 验证和限制

- 本轮新增加 **13 项**专项测试，合计 **159 项本地自动化测试通过**（完整回归、版本、Python 编译和 JS 语法在打包时再次执行）。
- 真实数据库 `PyMySQL` 连接、TLS 证书、数据库侧最小权限、Docker Compose 启动、GitHub Actions 云端 CI，以及 5000 行产品真实压测**尚未实机验证**。新增测试使用确定性本地模拟连接器；因此不能宣称 MySQL 已完成生产部署验收。
- 无任意 SQL，也不自动跨站抽取未经授权的数据库；真正的数据库用户必须由管理员在 MySQL Server 上授予只读权限。数据库只读事务不是数据库权限的替代品。
- 数据批次按原 V8 规则暂存、提交、受保护回滚；本轮没有实现多库 JOIN、增量 CDC、数据库写回、API OAuth 授权流程或通用数据关系图。

## 仍待完成的完整网站工厂需求

P4 完整可视化组件、整站模板兼容性和草稿隔离；P5 生产 SFTP/S3 原子发布和回滚；P6 多语言内容关系与 hreflang；Art Design Pro 官方工程完整编译；PostgreSQL/Redis 高可用、企业身份和正式安全/浏览器/容器验收。