企业官网建设流程全解析

1. 为什么非得在局域网里跑 DeepSeek Harness？——从“能用”到“敢用”的真实分水岭

你有没有试过在笔记本上直接拉起一个大模型服务，刚把curl命令敲完，浏览器还没刷新出来，风扇就已进入喷气式模式？或者更糟：模型接口明明返回了 200，但每次推理都卡在loading...，日志里只有一行模糊的CUDA out of memory，连具体哪层爆了都看不到？这不是配置问题，是环境错位——把本该部署在异构计算集群上的 AI Agent 平台，硬塞进单机开发环境里跑，就像让F1赛车手开着拖拉机去参加勒芒24小时耐力赛：方向是对的，但底盘、散热、油料系统全都不匹配。

DeepSeek Harness 不是普通 API 封装。它是一套带状态管理、工具调用链路、多轮对话上下文持久化、以及可插拔执行器（Executor）的轻量级 Agent 框架。官方 Demo 默认走 HuggingFace Inference Endpoints 或云厂商托管服务，图的是开箱即用；但一旦你真想把它嵌进内部知识库、接进工单系统、或让销售同事用自然语言查 CRM 数据，就必须面对三个绕不开的现实：

• 数据不出域：客户询价记录、合同条款、未公开产品参数——这些内容绝不能经由公网中转；
• 响应可控：不是所有请求都值得调度 7B 模型；有些只需规则引擎+关键词匹配，有些则必须触发 RAG 流程+重排模型，调度策略得自己攥在手里；
• 故障可溯：当某次“生成报价单”失败时，你得能立刻定位是向量库检索超时、还是 LLM 输出格式解析异常、抑或是 PDF 渲染服务挂了——而不是对着 CloudWatch 里一堆5xx码干瞪眼。

Docker 部署不是为了“时髦”，而是为这三件事划出清晰边界：容器镜像固化运行时依赖，docker-compose.yml明确定义服务拓扑与网络策略，volume绑定确保模型权重、向量索引、日志文件全部落盘可审计。我去年在某高校实验室落地类似平台时，最初用pip install -e .直接跑源码，两周内遭遇三次环境漂移——一次是 PyTorch 升级导致 FlashAttention 编译失败，一次是transformers版本不兼容引发 tokenizer 错位，还有一次纯粹因为同事本地装了cuda-toolkit 12.3而服务器只有12.1。最后我们砍掉所有pip install步骤，全部改用预编译镜像+--platform linux/amd64强制指定架构，上线后连续 142 天零环境相关故障。这就是局域网+Docker 的底层价值：它不解决模型能力问题，但它把“能不能稳定跑起来”这个基础命题，从玄学变成了工程可验证项。

提示：别被“局域网”三个字迷惑。它不等于“只能内网访问”。实际生产中，我们通过 Traefik 反向代理 + TLS 证书 + IP 白名单，让外部合作方也能安全调用特定 API 端点，而模型服务本身仍严格隔离在内网段。关键在于流量入口可控，而非物理位置封闭。

2. DeepSeek Harness 容器化不是“打包就完事”——拆解四个必须重写的模块

很多团队拿到官方 GitHub 仓库后，第一反应是docker build -t deepseek-harness .，然后发现镜像体积动辄 8GB+，启动耗时 90 秒以上，且一并发 5 个请求就 OOM。问题不在 Docker，而在没理解 Harness 的模块耦合逻辑。它表面是个单体应用，实则暗含四层隐性依赖，每层都需针对性容器化改造：

2.1 模型加载层：放弃“启动即加载”，改用懒加载+内存池

官方默认行为是在app.py初始化时，通过AutoModelForCausalLM.from_pretrained()一次性载入整个模型权重。这对 GPU 显存是毁灭性打击——以 DeepSeek-V2-Lite（2.4B 参数）为例，FP16 加载需约 5.2GB 显存，若同时加载 embedding 模型+reranker 模型，显存占用瞬间突破 12GB，远超多数消费级显卡上限。

我们改为三级加载策略：

• 冷启动阶段：仅初始化tokenizer和空model对象，显存占用 < 200MB；
• 首次请求触发：根据X-Model-NameHeader 或路由路径（如/v1/chat/completions/deepseek-v2-lite）动态加载对应模型，并缓存至torch.cuda.memory_reserved()分配的显存池；
• 空闲回收：模型实例空闲超 300 秒后，自动del model并调用torch.cuda.empty_cache()。

实现上，我们抽离出model_manager.py，核心代码如下：

# model_manager.py import torch from transformers import AutoTokenizer, AutoModelForCausalLM from typing import Dict, Optional class ModelManager: _instances: Dict[str, tuple] = {} # model_name -> (model, tokenizer) @classmethod def get_model(cls, model_name: str) -> tuple: if model_name in cls._instances: return cls._instances[model_name] # 动态构造模型路径（映射到 volume 挂载点） model_path = f"/models/{model_name}" tokenizer = AutoTokenizer.from_pretrained(model_path) # 关键：启用 flash attention 且禁用不必要的优化 model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16, device_map="auto", attn_implementation="flash_attention_2", # 必须显式指定 low_cpu_mem_usage=True ) cls._instances[model_name] = (model, tokenizer) return model, tokenizer

注意：attn_implementation="flash_attention_2"这行不能省。实测表明，在 A10G 上开启后，7B 模型首 token 延迟从 1.8s 降至 0.42s。但必须确保基础镜像已预装flash-attn==2.6.3（注意版本号，2.6.x 适配 CUDA 12.1，2.5.x 适配 11.8），否则运行时报ImportError: cannot import name 'flash_attn_func'。

2.2 向量库层：用 ChromaDB 替代 FAISS，规避共享内存陷阱

Harness 默认支持 FAISS 作为向量存储，但 FAISS 在容器环境下有致命缺陷：其IndexFlatL2实例依赖进程内共享内存（mmap），而 Docker 默认禁用SYS_ADMIN权限，导致多实例部署时向量索引无法跨容器同步，查询结果随机失效。

我们切换至 ChromaDB，原因有三：

• 它原生支持 HTTP Server 模式，所有向量操作走 REST API，彻底解耦存储与计算；
• 支持 SQLite 作为底层存储，单文件即可持久化，volume挂载极简；
• 内置hnsw算法，100 万条向量下 P95 查询延迟稳定在 15ms 内（实测数据）。

docker-compose.yml中新增服务：

chromadb: image: chromadb/chroma:0.4.24 ports: - "8000:8000" volumes: - ./chroma_data:/chroma_data environment: - CHROMA_DB_IMPL=duckdb+parquet - CHROMA_PERSIST_DIRECTORY=/chroma_data restart: unless-stopped

对应地，config.yaml中将向量库配置从：

vector_store: type: faiss path: /data/faiss_index

改为：

vector_store: type: chroma host: http://chromadb:8000 collection_name: internal_knowledge

2.3 工具执行层：所有外部调用必须经由subprocess+ 超时熔断

Harness 允许注册 Python 函数作为工具（Tool），比如get_weather(city: str)。但若直接在主线程调用requests.get()，一旦天气 API 响应超时，整个 FastAPI 事件循环就会被阻塞。我们强制所有工具函数走子进程沙箱：

# tools/weather_tool.py import subprocess import json import time def get_weather(city: str) -> str: try: # 启动独立子进程，硬性超时 8 秒 result = subprocess.run( ["python", "weather_client.py", city], capture_output=True, text=True, timeout=8 ) if result.returncode == 0: return result.stdout.strip() else: return f"工具调用失败: {result.stderr}" except subprocess.TimeoutExpired: return "工具调用超时，请稍后重试" except Exception as e: return f"工具执行异常: {str(e)}"

配套的weather_client.py是纯脚本，不依赖任何全局状态。这种设计牺牲了微秒级性能，但换来的是服务韧性——即使某个工具持续崩溃，也不会拖垮整个 Agent 核心。

2.4 日志与监控层：结构化日志 + Prometheus 指标导出

原始日志是print()拼接字符串，无法被 ELK 或 Loki 有效解析。我们统一接入structlog，并注入请求 ID、模型名称、token 计数等字段：

# logger.py import structlog import uuid structlog.configure( processors=[ structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.TimeStamper(fmt="iso"), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.UnicodeDecoder(), structlog.processors.JSONRenderer() # 关键：输出 JSON ], context_class=dict, logger_factory=structlog.stdlib.LoggerFactory(), ) logger = structlog.get_logger()

同时，集成prometheus-fastapi-instrumentator，暴露/metrics端点，监控指标包括：

• agent_request_total{model, status_code}：按模型和状态码统计请求数；
• agent_token_count{model, direction}：输入/输出 token 总数；
• agent_latency_seconds_bucket{model, le}：P90/P95 延迟直方图。

这些指标通过 Prometheus 抓取，Grafana 面板可实时查看各模型负载热力图，为后续扩缩容提供数据依据。

3. 构建最小可行镜像：从 8GB 到 1.2GB 的七步瘦身法

初始构建的镜像为何臃肿？根本原因是沿用了通用 Python 基础镜像（如python:3.11-slim），它包含大量编译工具链（gcc,g++,make）、文档包、测试套件，而这些在运行时完全无用。我们采用多阶段构建（Multi-stage Build），分七步精准裁剪：

3.1 阶段一：构建环境（Builder Stage）

使用nvidia/cuda:12.1.1-devel-ubuntu22.04作为构建基底，安装 CUDA Toolkit、cuDNN、PyTorch 预编译 wheel：

# Builder Stage FROM nvidia/cuda:12.1.1-devel-ubuntu22.04 AS builder # 安装必要构建工具 RUN apt-get update && apt-get install -y \ python3.11-dev \ python3.11-venv \ libopenblas-dev \ liblapack-dev \ && rm -rf /var/lib/apt/lists/* # 创建虚拟环境并升级 pip RUN python3.11 -m venv /opt/venv ENV PATH="/opt/venv/bin:$PATH" RUN pip install --upgrade pip # 安装 PyTorch 2.3.0+cu121（必须与 CUDA 版本严格匹配） RUN pip install torch==2.3.0+cu121 torchvision==0.18.0+cu121 torchaudio==2.3.0+cu121 --extra-index-url https://download.pytorch.org/whl/cu121 # 安装其他依赖（注意：只装源码，不装二进制） RUN pip install \ transformers==4.41.2 \ accelerate==0.30.1 \ flash-attn==2.6.3 \ chromadb==0.4.24 \ structlog==23.3.0 \ prometheus-fastapi-instrumentator==7.2.0

3.2 阶段二：运行环境（Runtime Stage）

切换至极致精简的nvidia/cuda:12.1.1-runtime-ubuntu22.04，它仅含 CUDA 运行时库，不含编译器：

# Runtime Stage FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04 # 创建非 root 用户（安全刚需） RUN groupadd -g 1001 -f appuser && useradd -r -u 1001 -g appuser appuser USER appuser # 复制构建阶段的 site-packages COPY --from=builder --chown=appuser:appuser /opt/venv/lib/python3.11/site-packages /opt/venv/lib/python3.11/site-packages COPY --from=builder --chown=appuser:appuser /opt/venv/bin/ /opt/venv/bin/ # 复制应用代码（排除 .git、__pycache__、tests） COPY --chown=appuser:appuser --exclude='*.git*' --exclude='__pycache__' --exclude='tests' . /app/ WORKDIR /app # 设置 PYTHONPATH 和 PATH ENV PYTHONPATH="/app" ENV PATH="/opt/venv/bin:$PATH" # 验证 CUDA 可用性（关键检查点） RUN python3.11 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'Device count: {torch.cuda.device_count()}')" # 暴露端口 EXPOSE 8000 # 启动命令（使用 gunicorn + uvicorn worker） CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "--worker-class", "uvicorn.workers.UvicornWorker", "--timeout", "120", "app:app"]

3.3 七步瘦身效果对比表

最终镜像体积稳定在1.23GB（docker images | grep deepseek），docker run启动时间压至11.3 秒（实测 A10G），较原始镜像提速 8.2 倍。

提示：--squash需在daemon.json中启用"features": {"buildkit": true}，且构建命令需加DOCKER_BUILDKIT=1前缀。这是 Docker 23.0+ 的默认行为，旧版需手动开启。

4. docker-compose.yml 的黄金配置：网络、存储与弹性伸缩的实战参数

docker-compose.yml不是静态配置清单，而是服务拓扑的“宪法”。我们基于三个月线上运行数据，提炼出五组不可妥协的核心参数：

4.1 网络策略：显式定义自定义网络 + IPv4 子网

避免使用默认 bridge 网络，因其 DNS 解析不稳定且端口映射易冲突：

networks: agent-net: driver: bridge ipam: config: - subnet: 172.28.0.0/16 # 预留足够地址空间 gateway: 172.28.0.1

所有服务均声明：

services: harness: networks: - agent-net # ... 其他配置 chromadb: networks: - agent-net # ... 其他配置

此举确保harness服务内可通过http://chromadb:8000稳定访问，DNS 解析延迟 < 2ms（实测），且避免与宿主机其他 Docker 网络冲突。

4.2 存储卷：区分bind mount与named volume的适用场景

• 模型权重：用bind mount（./models:/models:ro），便于人工更新模型文件，且ro标志防止容器意外写入；
• 向量数据库：用named volume（chroma_data:），由 Docker 管理生命周期，备份时只需docker volume inspect chroma_data获取路径；
• 日志文件：用bind mount（./logs:/app/logs），方便tail -f logs/app.log实时追踪；
• 配置文件：用bind mount（./config.yaml:/app/config.yaml:ro），支持热重载（Harness 支持SIGHUP信号触发配置重读）。

4.3 资源限制：GPU 分配 + CPU/Memory 的硬性约束

harness: deploy: resources: limits: memory: 12G cpus: '4.0' reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

关键点：

• reservations.devices确保容器独占 1 块 GPU，避免多容器争抢显存；
• limits.memory设为 12G 是经过压测的阈值：低于此值，7B 模型在 batch_size=2 时会触发 OOM Killer；高于此值，宿主机内存余量不足，影响其他服务；
• cpus: '4.0'表示最多使用 4 个逻辑 CPU 核心，匹配gunicorn --workers 2的线程模型（每个 worker 占用 2 核）。

4.4 健康检查：三层探测机制防“假活”

harness: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 start_period: 120s

但仅靠 HTTP 探针不够。我们在/health接口内嵌三层校验：

@app.get("/health") async def health_check(): # 1. 基础服务可用性 if not torch.cuda.is_available(): raise HTTPException(status_code=503, detail="CUDA unavailable") # 2. 模型加载状态（检查是否至少有一个模型已缓存） if len(ModelManager._instances) == 0: raise HTTPException(status_code=503, detail="No model loaded") # 3. 向量库连通性 try: chroma_client.heartbeat() except Exception as e: raise HTTPException(status_code=503, detail=f"ChromaDB unreachable: {str(e)}") return {"status": "healthy", "models_loaded": list(ModelManager._instances.keys())}

这样，当docker ps显示healthy时，代表 GPU、模型、向量库三者全部就绪，而非仅 Web 服务进程存活。

4.5 重启策略：unless-stopped+delay避免雪崩

harness: restart: unless-stopped deploy: restart_policy: condition: on-failure delay: 10s max_attempts: 3 window: 120s

• unless-stopped确保宿主机重启后服务自动拉起；
• on-failure仅在非 0 退出码时重启，避免因SIGTERM（正常关闭）误触发；
• delay: 10s给 GPU 驱动充分加载时间，实测 A10G 首次加载驱动需 7~9 秒；
• window: 120s是关键：若 2 分钟内连续失败 3 次，则永久停止，防止故障扩散。

5. 局域网部署后的第一课：如何让非技术人员“无感”使用这个 AI 平台？

技术闭环不等于价值闭环。我们曾在一个制造业客户的部署中栽过跟头：后端 API 全部跑通，Postman 测试完美，但业务部门反馈“根本不会用”。问题出在交互层缺失——他们需要的不是一个/v1/chat/completions接口，而是一个能粘贴 Excel 表格、点击按钮就生成周报的界面。

我们用三天时间搭出最小可行前端（MVP Frontend），核心原则是：零配置、零学习成本、结果可追溯。

5.1 架构极简：Nginx 静态服务 + FastAPI 代理

不引入 React/Vue 等框架，纯 HTML+JS，所有资源打包进nginx容器：

frontend: image: nginx:1.25-alpine ports: - "8080:80" volumes: - ./frontend/dist:/usr/share/nginx/html:ro depends_on: - harness

dist/目录由以下index.html构成：

<!DOCTYPE html> <html> <head> <title>AI 助手</title> <style> body { font-family: "Segoe UI", sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; } textarea { width: 100%; height: 120px; margin: 10px 0; } button { background: #007bff; color: white; border: none; padding: 10px 20px; } </style> </head> <body> <h1>智能知识助手</h1> <p>输入您的问题，系统将从内部知识库为您解答：</p> <textarea id="query" placeholder="例如：上季度华东区销售额是多少？"></textarea> <button onclick="sendQuery()">发送</button> <div id="response"></div> <script> async function sendQuery() { const query = document.getElementById('query').value; const respDiv = document.getElementById('response'); respDiv.innerHTML = '<p>思考中...</p>'; try { const res = await fetch('/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query }) }); const data = await res.json(); respDiv.innerHTML = `<p><strong>回答：</strong>${data.response}</p>`; } catch (e) { respDiv.innerHTML = `<p><strong>错误：</strong>${e.message}</p>`; } } </script> </body> </html>

关键创新在 Nginx 配置（nginx.conf）：

location /api/ { proxy_pass http://harness:8000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 关键：注入模型选择头，用户无需感知 proxy_set_header X-Model-Name "deepseek-v2-lite"; }

这样，前端完全不知道后端模型细节，所有请求自动带上X-Model-Name，业务人员只需打开http://192.168.1.100:8080，输入问题，点击发送——全程无任何技术术语。

5.2 结果可追溯：为每次交互生成唯一 ID 并存档

在 FastAPI 中，我们拦截所有/chat请求，生成 UUID 并记录到 SQLite：

# middleware.py from fastapi import Request, Response import sqlite3 import uuid def init_db(): conn = sqlite3.connect("/app/logs/interactions.db") conn.execute(""" CREATE TABLE IF NOT EXISTS interactions ( id TEXT PRIMARY KEY, timestamp DATETIME DEFAULT CURRENT_TIMESTAMP, query TEXT, response TEXT, model_name TEXT, tokens_in INTEGER, tokens_out INTEGER ) """) conn.close() @app.middleware("http") async def log_interaction(request: Request, call_next): if request.url.path == "/chat" and request.method == "POST": body = await request.body() query = json.loads(body.decode()).get("query", "") interaction_id = str(uuid.uuid4()) # 注入 ID 到请求头，供下游服务使用 request.state.interaction_id = interaction_id # 记录到 DB（异步写入，避免阻塞） conn = sqlite3.connect("/app/logs/interactions.db") conn.execute( "INSERT INTO interactions (id, query) VALUES (?, ?)", (interaction_id, query) ) conn.commit() conn.close() response = await call_next(request) return response

随后在/chat接口返回时，将interaction_id写入响应头：

@app.post("/chat") async def chat_endpoint(query: str, request: Request): # ... 业务逻辑 response = await generate_response(query) # 更新 DB 中的响应内容 conn = sqlite3.connect("/app/logs/interactions.db") conn.execute( "UPDATE interactions SET response=?, model_name=?, tokens_in=?, tokens_out=? WHERE id=?", (response, model_name, tokens_in, tokens_out, request.state.interaction_id) ) conn.commit() # 返回响应头 headers = {"X-Interaction-ID": request.state.interaction_id} return JSONResponse(content={"response": response}, headers=headers)

业务人员收到回复后，看到响应头里的X-Interaction-ID: 8a3b5c1d-2e4f-5a6b-8c9d-0e1f2a3b4c5d，即可在后台数据库中查到完整上下文，包括原始问题、模型输出、token 消耗——这比任何截图都更可靠。

最后分享一个小技巧：我们给每个新部署的平台生成一张“使用速查卡”，A4 纸打印，贴在工位旁。上面只有三行：

• ✅ 正确姿势：打开http://192.168.1.100:8080→ 输入问题 → 点击发送
• ❌ 常见误区：不要尝试修改 URL、不要安装 Chrome 插件、不要复制 curl 命令
• 💡 紧急联系：遇到“思考中...”超过 30 秒，请截图并发送给 IT 支持（附上页面右上角显示的 Interaction ID）
  这张纸让培训时间从 2 小时压缩到 5 分钟，且零投诉。技术的价值，永远体现在它消失于用户体验之后。