浅念
8cea7dee20
- SiteForge Enterprise V8.10.0-dev.1 upstream source (210 tests) - Fix: v8_workflows._mapped_input now reads both 类型/分类 columns so WXR imports keep post/product types instead of collapsing to page - Docs: trade-pro theme port spec (R3) and implementation plan Co-Authored-By: Claude Code <noreply@anthropic.com>
74 lines
5.6 KiB
Markdown
74 lines
5.6 KiB
Markdown
# 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 高可用、企业身份和正式安全/浏览器/容器验收。
|