pj0235-eai_agentplatform/docs/02_Architecture/AR04_部署架构.md

AR04 — 部署架构设计

版本：V1.3 | 部署模式：纯本地离线 · Go 单二进制 + SQLite · systemd 当前实现：Go 单二进制 + SQLite(eai_agentplatform.db) + 内网 Ollama(LLM/embedding) + systemd，无 Docker、无 MySQL、无 FAISS。 平台本体无 Python 运行时；本地语音转写是独立的 Python 边车进程（eai_agentplatform-asr.service，监听 127.0.0.1:8090，用户不可见），详见部署文档与 backend-go/deploy/DELIVERY.md 第 0/2.5 节。 知识链路：检索为 Go 原生实施（embed_gen 路由嵌入候选块 + 余弦召回，对齐 D07/D13）；分类/入库已彻底迁移到 Go，Python 的 knowledge_service 已删除。 完整部署步骤请见 docs/02_Architecture/部署文档.md。

---

1. 部署拓扑

                        ┌──────────────────────┐
                        │    内网员工浏览器     │
                        │   http://train.bosun │
                        └──────────┬───────────┘
                                   │
                             ┌─────▼──────┐
                             │   Nginx    │
                             │ :80 / :443 │
                             │            │
                             │ · 前端静态 │
                             │ · API 反代 │
                             │ · SSE 支持 │
                             └──┬──────┬──┘
                                │      │
                 ┌──────────────┘      └──────────────┐
                 │                                     │
           ┌─────▼──────┐                    ┌────────▼────────┐
           │ eai_agentplatform-server        │  Vue 静态打包   │
           │ :8080     │                    │  nginx html/    │
           │ 单二进制  │                    └─────────────────┘
           │ · Gin +   │
           │ · SQLite  │
           └──┬──┬──┬──┘
              │  │  │
  ┌───────────┘  │  └──────────────┐
  │              │                 │
┌──▼─────┐ ┌────▼───────┐ ┌──────▼──────────┐
│ SQLite │ │ data/kb_data│ │  LibreOffice    │
│ 单文件  │ │ 文件存储   │ │  + pdftotext    │
│ eai_platform.db │     │ │  (裸进程)         │
└────────┘ └────────────┘ └─────────────────┘
                             │
                             │ (文档转换)
                             ▼
                     ┌──────────────┐
                     │  内网 LLM    │
                     │  Ollama/     │
                     │  vLLM/网关   │
                     │  :11434      │
                     └──────────────┘

2. 服务清单

服务	端口/路径	运行方式	说明
Nginx	80/443	系统包	HTTP 反代 + 前端静态资源托管
eai_agentplatform-server	8080	Go 单二进制（CGO_ENABLED=0，静态链接）	Gin + GORM 后端 API（内嵌 SQLite）
SQLite	data/eai_agentplatform.db	内嵌	单文件关系数据（glebarez/sqlite 纯 Go 驱动，无需 CGO）
LibreOffice + pdftotext	裸进程	exec 调用	文档转 PDF/文本预览（非容器，不监听端口）
LLM 服务	11434	外置	内网 OpenAI 兼容接口（Ollama / vLLM / 网关）
本地语音转写（边车）	127.0.0.1:8090	本机可选	faster-whisper large-v3 + pyannote 3.1；仅回环监听，不对外

核心特征：无 Docker、无 MySQL、无 FAISS。后端为 Go 单二进制（本体无 Python 运行时），数据为 SQLite 单文件；知识检索为 Go 原生向量/关键词召回（align D07/D13）。语音转写另有一个本地 Python 边车服务（见上表末行），它是可选件：不装则转写走云端路由。

3. Nginx 关键配置

# SPA 路由
location / {
    try_files $uri $uri/ /index.html;
}

# API 反代 + SSE
location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

# 媒体文件预览（Go 二进制直出）
location /api/media/ {
    proxy_pass http://127.0.0.1:8080;
}

client_max_body_size 2048M;

4. systemd 管理

[Unit]
Description=eai_agentplatform Server
After=network.target

[Service]
Type=simple
User=eai_agentplatform
Group=eai_agentplatform
WorkingDirectory=/opt/eai_agentplatform
ExecStart=/opt/eai_agentplatform/eai_agentplatform-server
Restart=on-failure
RestartSec=5
EnvironmentFile=/opt/eai_agentplatform/.env

# 安全加固
ExecStartPre=/opt/eai_agentplatform/eai_agentplatform-server migrate
ProtectSystem=strict
ProtectHome=true
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

5. 安全边界

层级	措施
网络	仅监听内网，不暴露公网端口
认证	JWT token 校验 + bcrypt 密码
鉴权	后端 API role 校验（非前端）
文件	白名单扩展名 + UUID 命名 + proxy_pass 内部预览
数据库	SQLite 单文件（系统级文件权限，systemd ProtectSystem=strict）
备份	内建定期 VACUUM INTO，默认 24h 间隔，保留 7 份
LLM	仅内网地址，严禁公网 API