【第 9 篇：本地化部署——从 0 到 1 的企业级系统部署全记录】

第 9 篇：本地化部署——从 0 到 1 的企业级系统部署全记录

系列记录：《从零搭建企业级 LLM 应用》，这是第 9 篇
上一篇：数据接口管理——从模拟到真实与企业级接口治理

一、系统架构概览：在部署之前，先把"要部署什么"搞清楚

本项目是一个知识库智能体平台，基于多智能体（Multi-Agent）架构搭建，核心支撑文档智能问答、数据分析、标准化 API 对接等业务能力。支持局域网、隔离内网环境本地化部署，所有业务数据、文档数据、模型推理数据均留存本地，无需上传公网。

整个系统可以拆成三层来理解：

1.1 第一层：四大核心子服务

1.2 第二层：三大核心 AI 模型

三大模型显存/内存总需求 ≥19GB，单卡 24GB 显存设备可完全承载。

1.3 第三层：知识库平台（Dify / RAGFlow）

系统依赖外部知识库引擎完成文档解析、向量存储与检索。支持 Dify 与 RAGFlow 两种主流平台，均为 Docker Compose 一键部署，选其一即可。

1.4 整条调用链

用户浏览器 → 前端(8080) → 业务API(8000) ├── 代码沙箱(8001) —— Agent 生成代码的隔离执行 ├── 知识库平台(80/443) —— Dify/RAGFlow 文档检索 ├── Ollama(11434) —— LLM 推理 ├── vLLM/Xinference(9997) —— Embedding + Rerank └── 外部系统接口 —— 通过 data_interface/ 接入的管理平台等

二、硬件与运行环境规划

2.1 硬件配置标准

以下配置包含 LLM、Embedding、Rerank 三类模型 + Dify 知识库平台运行所需的全部资源，均预留 10% 运行冗余。

本项目实际部署环境：Ubuntu 22.04 LTS、2 × NVIDIA RTX 4090 (24GB × 2)、128GB RAM、2TB SSD。

2.2 LLM 推理模型选型

2.3 软件依赖环境

三、AI 模型部署

3.1 LLM 推理模型（Ollama）

最简单的部署方式：

# 安装 Ollama（官方一键脚本）curl-fsSLhttps://ollama.com/install.sh|sh# 拉取模型ollama pull qwen2.5:14b# 验证ollama run qwen2.5:14b"你好，请介绍一下自己"

Ollama 默认监听11434端口，服务启动后通过http://localhost:11434调用。更高配环境可替换为qwen2.5:32b或qwen2.5:72b。

3.2 向量嵌入模型（vLLM / Xinference）

Embedding 与 Rerank 模型需额外的推理框架部署。以 Xinference 为例：

# 安装 Xinferencepipinstallxinference# 启动服务xinference-local--host0.0.0.0--port9997# 通过 Web UI (http://localhost:9997) 注册并启动模型：# - qw-multimodal-embedding-v1（embedding 模型，≥3GB 显存）# - qwen3-rerank（rerank 模型，≥4GB 显存）

两个模型可共用同一张显卡部署。

3.3 模型部署验证

# 验证 LLMcurlhttp://localhost:11434/api/generate-d'{"model":"qwen2.5:14b","prompt":"你好"}'# 验证 Embeddingcurlhttp://localhost:9997/v1/embeddings\-H"Content-Type: application/json"\-d'{"model":"qw-multimodal-embedding-v1","input":"测试文本"}'# 验证 Rerankcurlhttp://localhost:9997/v1/rerank\-H"Content-Type: application/json"\-d'{"model":"qwen3-rerank","query":"测试问题","documents":["文档1","文档2"]}'

四、知识库平台部署

任选 Dify 或 RAGFlow，通过 Docker Compose 部署：

# RAGFlow（本项目实际使用）gitclone https://github.com/infiniflow/ragflow.gitcdragflow/dockerdockercompose up-d

部署完成后访问http://<服务器IP>，完成初始化配置：

• 在平台中创建知识库
• 配置 Embedding 模型指向http://localhost:9997/v1
• 配置 Rerank 模型
• 获取 API Key，填入项目的.env配置文件

注意：知识库平台与系统主服务同机部署时，服务器总内存建议不低于 32GB。

五、系统服务部署

5.1 部署前置核验清单

部署前逐项确认：

• Python ≥ 3.10，pip、Git 工正常运行
• pip 镜像源已配置（国内服务器推荐清华源）
• 项目代码已完整传输至服务器指定目录
• 知识库平台已完成初始化，已获取有效 API Key
• Ollama、vLLM / Xinference 模型服务已部署并可正常访问
• 防火墙已开放全部所需内网端口（参考 1.4 节端口清单）
• .env环境配置文件已按实际业务环境完整填写，SECRET_KEY 已修改为随机值

5.2 标准化部署步骤

# 步骤 1：获取项目代码cd/optgitclone<项目仓库地址>cd项目目录# 步骤 2：创建 Python 虚拟环境python3-mvenv venvsourcevenv/bin/activate# 步骤 3：安装项目依赖（国内服务器使用清华源加速）pipinstall-rrequirements.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple# 步骤 4：配置环境变量cp.env.example .env# 编辑 .env，填写：模型服务地址、知识库 API Key、JWT SECRET_KEY 等# 步骤 5：初始化数据库（自动创建默认管理员账号 admin / admin123）python scripts/init_db.py

5.3 一键启动脚本

完成上述配置后，使用start_ubuntu.sh一键启动全部服务：

#!/bin/bash# start_ubuntu.sh — Ubuntu 环境一键启动脚本set-eSCRIPT_DIR="$(cd "$(dirname"$0")"&&pwd)" cd "$SCRIPT_DIR" SERVER_IP="XXX.XXX.X.XXX" PORTS=(8000 8001 8002 8080) # 1. 激活虚拟环境 source venv/bin/activate # 2. 释放端口（防止上次启动残留） for port in "${PORTS[@]}"; do pids=$(lsof-titcp:"$port"2>/dev/null||true)if [ -n "$pids" ]; then kill -9$pids2>/dev/null || true fi done # 3. 初始化数据库 python scripts/init_db.py # 4. 启动四个服务（后台运行，日志落盘） mkdir -p logs nohup python -m uvicorn code_executor:app --host 0.0.0.0 --port 8001 > logs/code_executor.log 2>&1 & nohup python -m uvicorn api:app --host 0.0.0.0 --port 8000 > logs/api.log 2>&1 & nohup python -m uvicorn alarm_api:app --host 0.0.0.0 --port 8002 > logs/alarm_api.log 2>&1 & nohup python -m http.server 8080 --directory . --bind 0.0.0.0 > logs/http_server.log 2>&1 & # 5. 就绪提示 sleep 5 echo "系统已启动！" echo "本机: http://127.0.0.1:8080/html_files/login-page.html" echo "局域网: http://${SERVER_IP}:8080/html_files/login-page.html"

脚本的几个设计要点：

• set -e：任何命令失败即退出，拒绝带伤启动
• 端口释放：启动前先lsof -ti+kill -9清理残留进程
• nohup+ 日志：服务后台运行，stdout/stderr 全部落盘到logs/
• --bind 0.0.0.0：http.server 默认只绑定 localhost，必须显式绑定0.0.0.0才能从其他机器访问

六、部署踩坑实录：五个真实问题与解决

下面记录的是从"代码拉下来"到"全团队都能用"之间，实际遇到的五个坑。这些问题如果在同一台 Windows 开发机上跑start.bat，一个都不会出现——它们全部来自"换了一台机器"这个动作。

坑 1：端口冲突——8080 已被 RAGFlow 占用

手动启动python3 -m http.server 8080直接报Address already in use。

$sudolsof-i:8080docker-pr3649root 7u IPv479201TCP *:http-alt(LISTEN)

服务器上已部署 RAGFlow（知识库引擎），Docker 容器占用了 80、443、8080 端口。

决策：不碰 RAGFlow（别人部署的生产服务），把自己的端口整体迁移。

最终端口映射：

坑 2：防火墙拦截——iptables 拒绝了 28000 系列端口

服务在服务器上本地curl http://127.0.0.1:28080正常，但从其他电脑curl http://XXX.XXX.X.XXX:28080直接 timeout。

确认服务在监听之后，检查 iptables：

$sudoiptables-LINPUT-n--line-numbers Chain INPUT(policy ACCEPT)1ACCEPT all --0.0.0.0/00.0.0.0/0 ctstate RELATED,ESTABLISHED,DNAT2ACCEPT all --0.0.0.0/00.0.0.0/03INPUT_direct all --0.0.0.0/00.0.0.0/04INPUT_ZONES all --0.0.0.0/00.0.0.0/05DROP all --0.0.0.0/00.0.0.0/0 ctstate INVALID6REJECT all --0.0.0.0/00.0.0.0/0 reject-with icmp-host-prohibited

第 6 条的REJECT all拒绝了所有未被前面规则匹配的流量。那为什么 80/8080（RAGFlow）能通？因为第 1 条的DNAT——Docker 在启动容器时自动插入 DNAT 规则，让 RAGFlow 的端口走了 Docker 转发链路，绕过了最后的 REJECT。手动启动的 28000 系列没有这个待遇，直接落入第 6 条被拒绝。

修复：

sudofirewall-cmd --add-port=28000/tcp--permanentsudofirewall-cmd --add-port=28001/tcp--permanentsudofirewall-cmd --add-port=28002/tcp--permanentsudofirewall-cmd --add-port=28080/tcp--permanentsudofirewall-cmd--reload

执行后立刻能通。

坑 3：前端 API 地址硬编码——23 处localhost:8000

端口通了，登录页面能打开，但一点登录就报"网络错误，请检查服务是否启动"。

打开浏览器开发者工具一看，所有 fetch 请求都指向http://localhost:8000——这是开发机上的地址，API 已经搬到XXX.XXX.X.XXX:28000了。

搜索html_files/目录，8 个文件共 23 处硬编码的localhost:8000：

修复：全局替换http://localhost:8000→http://XXX.XXX.X.XXX:8000。

反思：这是典型的技术债。开发阶段图省事直接写了localhost:8000，因为只有一个环境。更好的做法是通过window.location.hostname动态构造 API 地址，或提供一个可配置的config.js。

坑 4：Windows 客户端出站防火墙

改完 API 地址后，局域网内其他电脑都能登录了，但个别 Windows 客户端仍然不行。

无痕模式试过、DNS 缓存清过、浏览器换过——都排除。最终定位到** Windows Defender 防火墙的出站规则**：Windows 防火墙有时会阻止非标准端口（28000 系列）的出站连接。

修复：

1. 临时关闭 Windows 防火墙 → 能登录，确认根因
2. 在防火墙高级设置中创建出站规则，放行 TCP 端口28000, 28001, 28002, 28080
3. 重新开启防火墙

坑 5：环境变量未正确配置导致连接知识库失败

部署后智能问答功能正常，但涉及知识库检索时返回错误。排查发现.env中知识库 API Key 仍为示例值，未替换为实际的知识库平台密钥。

修复：检查并更新.env中所有必填项——模型服务地址、知识库 API Key、JWT SECRET_KEY、数据库路径等。特别注意上线环境必须修改默认的 SECRET_KEY。

七、安全与运维建议

7.1 端口安全策略

所有端口仅对内网防火墙/安全组开放，禁止公网映射。

7.2 运维注意事项

• 资源冗余：多模型同时运行对硬件要求较高，需预留充足冗余，避免高并发下服务卡顿或宕机
• 内存保障：知识库平台与主服务同机部署时，务必保障服务器内存 ≥ 32GB
• 定期备份：数据库文件、知识库文档、模型权重文件均需纳入备份计划
• 日志监控：logs/目录下各服务的运行日志是排查问题的第一手资料，建议定期轮转清理

八、总结：部署的本质

回头看整个部署过程，真正的挑战不在"启动服务"——三条uvicorn命令几秒钟就跑起来了。

实际花费时间解决的，全部来自环境差异引发的连锁问题：

服务器上已有 RAGFlow → 端口 8080 被占 → 整体迁移到 28000 系列 → iptables REJECT 非标准端口（Docker DNAT 绕过了所以 80/8080 没事） → firewalld 放行 4 个端口 → 前端 API 地址 23 处 localhost:8000 全部失效 → 批量替换为 XXX.XXX.X.XXX:28000（更好的方法是设一个全局api变量的配置，直接在配置环境时生效） → 个别 Windows 客户端出站防火墙拦截 28000 端口 → 创建出站规则

这条链上的每一个问题，换一个环境都会遇到。所以部署的核心不是"怎么启动"，而是怎么让换了一个环境之后，所有依赖关系仍然正确"。

本次部署产出的关键文件