# 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. 环境准备（系统级依赖） ```bash # 系统依赖：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） ```bash # 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` 关键项： ```bash 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 配置 ```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 ```bash 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 环境。 ```bash 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；知识检索自动降级为关键词匹配，不影响其他模块。 --- ## 启动/停止 ```bash 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 历史。