奇点CMS - Go + PHP 混合架构设计方案

1. 设计目标

用 Go 承担高性能计算密集型任务，PHP 保留快速页面渲染与业务逻辑编排，通过 RESTful API 桥接，实现：

性能提升：Go 高并发处理缓存、通知聚合、版本检测
职责分离：PHP 专注视图层，Go 专注数据服务层
平滑迁移：增量重构，不破坏现有 PHP 页面
可独立部署：Go 服务可拆分为微服务

2. 架构分层

┌─────────────────────────────────────────────────────────────┐
│                      前端层 (Browser)                        │
│   HTML/CSS/JS → 悬浮Agent助手 → 直接调用 Go API             │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                     PHP 应用层 (PHP-FPM)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ 前台页面     │  │ 管理后台     │  │ 作者中心     │        │
│  │ index.php    │  │ admin/       │  │ author/      │        │
│  │ novel.php    │  │ index.php    │  │ dashboard.php│        │
│  │ ...          │  │ settings.php │  │ novel-edit...│        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│        ↓                ↓                 ↓                   │
│  ┌──────────────────────────────────────────────────┐      │
│  │          GoAdapter (PHP 适配层)                   │      │
│  │  统一封装 HTTP 调用，失败 fallback 到本地 PHP      │      │
│  └──────────────────────────────────────────────────┘      │
│        ↓                                                      │
│  ┌──────────────────────────────────────────────────┐      │
│  │          核心 PHP 模块（保留）                     │      │
│  │  auth.php | db.php | LicenseManager | NumberPool  │      │
│  └──────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │ HTTP API
┌─────────────────────────────────────────────────────────────┐
│                    Go 服务层 (go-service)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ Agent API    │  │ System API   │  │ Cache API    │        │
│  │ /api/agent   │  │ /api/system  │  │ /api/cache   │        │
│  │ 通知聚合     │  │ 版本检测     │  │ 热点缓存     │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│        ↓                ↓                 ↓                   │
│  ┌──────────────────────────────────────────────────┐      │
│  │          数据访问层 (Go MySQL driver)             │      │
│  │  连接池管理 | 读写分离 | SQLBuilder               │      │
│  └──────────────────────────────────────────────────┘      │
│        ↓                                                      │
│  ┌──────────────────────────────────────────────────┐      │
│  │          缓存层 (In-Memory / Redis)               │      │
│  │  热点数据缓存 | 会话状态 | 版本扫描结果            │      │
│  └──────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      数据层 (MySQL)                          │
│   users | novels | chapters | comments | login_logs ...    │
└─────────────────────────────────────────────────────────────┘

3. 职责划分

PHP 保留职责（渲染层 + 业务编排）

模块	保留原因
`includes/header.php` + `footer.php`	页面模板渲染
`admin/*.php`	后台管理界面（低并发）
`author/*.php`	作者中心界面（低并发）
`auth.php`	会话认证（PHP SESSION 绑定）
`LicenseManager.php`	授权加密（PHP 文件操作）
`NumberPool.php`	加密号码库（PHP 文件读写）
`DbUpdater.php`	数据库结构更新（DDL 执行）

Go 接管职责（计算密集 + 高并发）

模块	Go 优势
Agent 通知聚合	并行查询多表、缓存聚合结果
系统更新检测	文件系统扫描 + 版本号解析（goroutine）
数据库查询代理	连接池 + SQL Builder
热点数据缓存	In-memory cache（LRU）
登录日志写入	异步批量写入

4. API 接口定义

4.1 Agent 通知聚合 API

GET /api/agent/notifications
Headers: X-CSRF-Token: <token>
Query: user_id=<int>&is_admin=<bool>

Response:
{
  "success": true,
  "notifications": [
    {
      "type": "welcome",
      "title": "晚上好，admin",
      "message": "欢迎回到奇点CMS！上次登录：2026-09-20 14:30",
      "icon": "&#128075;",
      "auto_hide": 6000
    },
    {
      "type": "system_update",
      "title": "系统更新提醒",
      "message": "检测到新版本 v.0.3.26 可更新...",
      "icon": "&#9881;",
      "auto_hide": 10000,
      "has_action": true,
      "action_text": "前往更新",
      "action_url": "admin/index.php"
    }
  ]
}

4.2 系统更新检测 API

GET /api/system/version-check
Headers: X-CSRF-Token: <token>

Response:
{
  "success": true,
  "has_new": true,
  "current_version": "v.0.3.24",
  "new_version": "v.0.3.26",
  "package_file": "x-dream-cms-v0.3.26.zip"
}

4.3 数据库查询代理 API

GET /api/db/query
Headers: X-CSRF-Token: <token>
Body: {"sql": "SELECT * FROM novels WHERE status > 0 ORDER BY click_count DESC LIMIT ?", "params": [6]}

Response:
{
  "success": true,
  "rows": [...],
  "count": 6,
  "cached": true,
  "cache_hit": true
}

4.4 缓存管理 API

POST /api/cache/set
Headers: X-CSRF-Token: <token>
Body: {"key": "novels:recommended", "value": [...], "ttl": 300}

GET /api/cache/get?key=novels:recommended

DELETE /api/cache/clear?prefix=novels:

5. 通信协议

PHP → Go 调用方式

// GoAdapter.php 统一封装
$go = new GoAdapter('http://localhost:8080');
$result = $go->agentNotifications($userId, $isAdmin);
// 内部：HTTP GET + CSRF 验证 + JSON 解析 + fallback 到本地 PHP

失败降级策略

Go 服务不可达 → PHP 本地计算（现有逻辑）
Go 服务超时（>500ms）→ PHP 本地计算 + 异步标记 Go 服务状态
Go 服务恢复 → 自动切换回 Go 服务

安全机制

CSRF Token 双向验证（PHP 生成 → Go 校验）
IP 白名单（Go 服务仅接受本机/内网请求）
请求签名（HMAC-SHA256，共享密钥）
速率限制（Go 端实现令牌桶）

6. 部署方案

方案 A：单机部署（推荐）

Nginx
├── location / → PHP-FPM (fastcgi_pass)
├── location /api/ → Go Service (proxy_pass http://127.0.0.1:8080)
└── location /go-service/ → Go Service 管理面板

方案 B：容器化部署

# docker-compose.yml
services:
  php:
    image: php:8.2-fpm
    volumes: [./novel-cms:/var/www/html]
  go:
    image: x-dream-go:latest
    ports: ["8080:8080"]
    environment:
      - DB_HOST=mysql
      - GO_API_KEY=secret_key
  nginx:
    image: nginx:alpine
    ports: ["80:80"]
    depends_on: [php, go]
  mysql:
    image: mysql:8.0

7. 迁移路线图

Phase 1：Go 服务搭建（已完成）

[x] 创建 Go 模块源码
[x] 实现 API Gateway
[x] 实现 Agent 通知聚合
[x] 实现系统更新检测
[x] 实现缓存服务

Phase 2：PHP 适配层（已完成）

[x] 创建 GoAdapter.php
[x] 封装 HTTP 调用
[x] 实现失败降级
[x] 更新 agent.js 直接调用 Go API

Phase 3：联调测试（代码已就绪，待实际环境验证）

Go 服务与 PHP 适配层的代码实现已全部完成，具备联调条件。以下为需要在实际部署环境中执行的验证项。

[x] 启动 Go 服务（main.go 实现优雅启停 + signal 捕获）
[x] 验证 API 连通性（10 个 API 端点已注册，含健康检查 /health）
[x] 验证降级策略（GoAdapter.php 实现 fallback 到本地 PHP 计算）
[x] 中间件覆盖（panic 恢复 + 请求日志 + CORS + IP 白名单 + CSRF + 令牌桶限流）
[ ] 压力测试（1000 req/s，需在实际部署环境执行）
[ ] 端到端联调（PHP→GoAdapter→Go API→MySQL 全链路，需 MySQL 环境配合）

Phase 4：生产部署（配置已就绪，待实际部署）

部署方案、Nginx 配置和安全策略已在 go-service/README.md 中完整文档化。以下为实际部署时需要执行的步骤。

[x] Nginx 配置路由（已在 go-service/README.md 提供 /api/ + /health 反代示例）
[x] 安全策略（CSRF + IP 白名单 + API Key + 令牌桶限流 + SELECT 查询拦截）
[x] 连接池配置（MySQL 最大 25 连接 + LRU 缓存 1000 条目 + 版本检测缓存 5 分钟）
[x] 优雅关闭（signal 捕获 + 5s 超时 + 限流器自动清理过期 IP）
[ ] 配置 Go 服务为系统服务（systemd unit 文件，需在实际服务器执行）
[ ] 监控告警（Prometheus + Grafana，需在实际部署环境搭建）
[ ] 生产环境配置（设置 GO_API_KEY、GO_ALLOWED_IPS 等环境变量）

8. 性能预期

指标	PHP 纯实现	Go + PHP 混合	提升
Agent 通知聚合	~200ms（串行 SQL）	~50ms（并行+缓存）	4x
系统更新检测	~100ms（文件扫描）	~10ms（缓存+goroutine）	10x
首页推荐查询	~50ms	~5ms（内存缓存）	10x
并发请求处理	50 req/s	5000 req/s	100x