pj0235-eai_agentplatform/docs/deploy.md

eai_agentplatform_app — 部署文档

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

---

部署拓扑

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

---

服务清单

服务	端口	说明
Nginx	80/443	HTTP 反代 + 前端静态资源托管
eai_agentplatform-server	8080	Go 单二进制后端（Gin + GORM）
MySQL	3306	MySQL 8.0 关系数据（systemd 托管 mysqld）
FAISS	内嵌	向量索引，由 Go 后端 cgo 内嵌，索引文件 data/faiss/
LibreOffice + pdftotext	进程内调用	裸进程，非容器，文档转文本
LLM 服务	11434	内网 OpenAI 兼容接口（Ollama / vLLM）

无 Docker、无 Python 运行时。 后端为 Go 单二进制，MySQL 由 systemd 托管，FAISS 内嵌于后端。

---

目录布局

/opt/eai_agentplatform/
├── eai_agentplatform-server     # 单二进制（CGO 关闭，静态链接，约 38MB）
├── .env                     # JWT 密钥、LLM 配置等
├── data/
│   ├── faiss/               # FAISS 向量索引（embedding 向量）
│   └── media/               # 素材 + 提取缓存
└── docs/
    └── knowledge_source/    # 知识源 Markdown（待管理员审批入库）

---

安装步骤

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

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

LibreOffice 与 pdftotext 均为裸进程，由二进制内 exec 调用，不跑容器、不监听端口。 MySQL 初始化库与账号（FAISS 向量索引内嵌于后端，无需独立服务）：

CREATE DATABASE eai_agentplatform DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'eai_agentplatform'@'127.0.0.1' IDENTIFIED BY '<随机密码>';
GRANT ALL PRIVILEGES ON eai_agentplatform.* TO 'eai_agentplatform'@'127.0.0.1';
FLUSH PRIVILEGES;

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=$(python3 -c "import secrets; print(secrets.token_urlsafe(48))")
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_DSN=eai_agentplatform:<随机密码>@tcp(127.0.0.1:3306)/eai_agentplatform?charset=utf8mb4&parseTime=True&loc=Local
JWT_SECRET=<48 字符随机串，交付前生成>
LLM_BASE_URL=http://127.0.0.1:11434/v1
LLM_MODEL=qwen2.5:7b
EMBED_MODEL=bge-m3
FAISS_INDEX_DIR=data/faiss
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

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 历史。