eaiadminandClaude Code
c1af86c934
按用户指示做**一包提交**，不按工作流拆分。本提交刻意混合了多条并行线：
· 本地 ASR 接管：audio 成为与 chat/embed/image/video 同等的路由类别
（IsLocalRoute 单一判据、audio 健康探测、default_audio_route、
auto 占位、GET /api/ai/routes/audio、回退云端时界面明示「音频已出网」）
· LLM 调用层：ctx 贯穿、ToolCall/ToolSchema、EmptyCompletionError /
TransientUpstreamError（按错误类型而非文案判重试）
· 编排 Agent：general_assistant orchestrate/persistence/spec_driver
· 联网搜索：internal/search（playwright）
· 网盘：backend + 前端
· 前端 UI：导航/路由/工作台若干页
· 交付文档：DELIVERY.md / AR04 / 部署文档的「无 Python」表述据实改写，
新增 eai_agentplatform-asr.service、asr.env、clonezilla-cleanup 清 ~/asr-poc
不分拆的原因：dev 早期，粒度不该打断工作节奏。且实测过——这些改动
**在编译上是同一个单元**（llm.go 的 ctx 签名变更牵动 12 个调用点，
chat_message.go 的 ctx 改动又与编排重写同处一个 hunk），拆出来的中间态编不过。
详见 TOP_CODING_RULES.md G14.5 与 bugs_and_errors.md E09。
Co-Authored-By: Claude Code <noreply@anthropic.com>
221 lines
9.1 KiB
Markdown
221 lines
9.1 KiB
Markdown
# 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 历史。
|