pj0235-eai_agentplatform/docs/02_Architecture/部署文档.md

eai_agentplatform — 部署文档

版本：V1.3 | 部署模式：纯本地离线 · Go 单二进制 + SQLite · systemd · Clonezilla 整盘克隆 最后更新：2026-08-16

---

部署拓扑

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

---

服务清单

服务	端口	说明
Nginx	80/443	HTTP 反代 + 前端静态资源托管
eai_agentplatform-server	8080	Go 单二进制后端（Gin + GORM）
SQLite	内嵌	单文件数据 data/eai_agentplatform.db（glebarez/sqlite 纯 Go 驱动，无需 CGO）
LibreOffice + pdftotext	进程内调用	裸进程，非容器，文档转文本
LLM 服务	11434	内网 OpenAI 兼容接口（Ollama / vLLM）

无 Docker、无 MySQL、无 FAISS 运行时；平台本体无 Python 运行时。 后端为 Go 单二进制，数据为 SQLite 单文件（data/eai_agentplatform.db），知识检索为 Go 原生向量/关键词召回（embed_gen 嵌入 + 余弦，对齐 D07/D13），不依赖外部向量库。

例外：本地语音转写（ASR）是独立的 Python 服务，eai_agentplatform-asr.service 常驻在 127.0.0.1:8090，占用约 13.5 GB 磁盘（venv + 模型）。它是可选件：不装则转写自动走云端路由，界面会在结果上标注「音频已离开本机」。安装与验证见 backend-go/deploy/DELIVERY.md 第 2.5 节。

---

目录布局

/opt/eai_agentplatform/
├── eai_agentplatform-server     # 单二进制（CGO 关闭，静态链接）
├── .env                     # JWT 密钥、LLM 配置等
├── data/
│   ├── eai_agentplatform.db # SQLite 单文件数据（自动迁移建表）
│   ├── kb_data/             # 知识库素材物理文件
│   └── backups/             # 定期备份（见 BACKUP_* 配置）
└── docs/
    └── knowledge_source/    # 知识源 Markdown（待管理员审批入库）

---

安装步骤

1. 环境准备（系统级依赖）

# 系统依赖：Nginx（前端+反代）+ LibreOffice + pdftotext（文档转换裸进程）
apt update && apt install -y nginx libreoffice poppler-utils

LibreOffice 与 pdftotext 均为裸进程，由二进制内 exec 调用，不跑容器、不监听端口。 数据库为 SQLite 单文件：无需安装任何数据库服务。后端首次启动用 GORM 自动建表， 数据写入 data/eai_agentplatform.db（由 .env 的 DB_PATH 指定）。

2. 部署后端（单二进制 + systemd）

# 2.1 拷贝二进制 + 建服务账号
sudo install -m 0755 eai_agentplatform-server /opt/eai_agentplatform/eai_agentplatform-server
sudo useradd -r -s /usr/sbin/nologin eai_agentplatform
sudo mkdir -p /opt/eai_agentplatform/data/kb_data /opt/eai_agentplatform/docs/knowledge_source
sudo chown -R eai_agentplatform:eai_agentplatform /opt/eai_agentplatform

# 2.2 生成 .env（JWT 密钥随机）
sudo -u eai_agentplatform cp deploy/eai_agentplatform.env /opt/eai_agentplatform/.env
NEW_SECRET=$(openssl rand -base64 48 | tr -d '\n')
sudo sed -i "s|^JWT_SECRET=.*|JWT_SECRET=$NEW_SECRET|" /opt/eai_agentplatform/.env

# 2.3 安装 systemd 单元并启动
sudo install -m 0644 deploy/eai_agentplatform.service /etc/systemd/system/eai_agentplatform.service
sudo systemctl daemon-reload
sudo systemctl enable --now eai_agentplatform

# 2.4 验证
curl http://127.0.0.1:8080/api/health   # {"status":"ok","service":"eai_agentplatform-app",...}

.env 关键项：

PORT=8080
DB_PATH=data/eai_agentplatform.db
JWT_SECRET=<48 字符随机串，交付前生成>
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=qwen2.5:7b
EMBED_MODEL=bge-m3
KB_DATA_DIR=data/kb_data
KNOWLEDGE_SOURCE_DIR=/opt/eai_agentplatform/docs/knowledge_source
LIBREOFFICE_BIN=/usr/bin/libreoffice
PDFTOTEXT_BIN=/usr/bin/pdftotext

---

Nginx 配置

server {
    listen 80;
    server_name train.bosun;

    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反代到 Go 单二进制
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # SSE 支持（AI 流式响应）
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }

    # 媒体预览（Go 静态托管，直接反代）
    location /media/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
    }

    client_max_body_size 2048M;
}

---

LLM 服务配置示例

使用 Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:7b          # LLM（中文能力强）
ollama pull bge-m3              # 嵌入模型（向量检索）
# 默认监听 127.0.0.1:11434，Go 二进制直接走 OpenAI 兼容 /v1 接口

使用 vLLM（可选，外部 LLM 网关）

默认推荐 Ollama（无 Python 运行时）。如需以 vLLM 作为 LLM 网关可按下述配置，但该网关不属于交付系统本体，目标机需自行准备 Python 环境。

pip install vllm
python -m vllm.entrypoints.openai.api_server \
    --model /path/to/model --port 11434 --host 0.0.0.0

LLM 配置优先级：system_config 表 → .env。缺 llm_base_url / llm_model 时，AI 接口返回 501；知识检索自动降级为关键词匹配，不影响其他模块。

---

启动/停止

sudo systemctl restart eai_agentplatform   # 重启
sudo systemctl stop    eai_agentplatform   # 停止
sudo systemctl status  eai_agentplatform   # 状态 / 日志
journalctl -u eai_agentplatform -f         # 实时日志

---

交付：Clonezilla 整盘克隆

1. 原型机完成「交付前清理」（改密、随机 JWT、清测试数据、删源代码）——详见 backend-go/deploy/DELIVERY.md。
2. Clonezilla device-device 整盘复制到同型号客户机。
3. 客户机首启即用：systemd 自动拉起，无任何依赖安装步骤。

交付红线：二进制静态链接、无 .go/go.mod 源码、.env 无占位符、管理员密码非默认值、无测试数据、无 .git 与 shell 历史。