大模型应用开发 / 系统课时

部署并保护项目接口

部署并保护项目接口

学习目标

完成本课后,你将能够:

  • 使用 Docker Compose 编排 Ollama、知识助手后端和 Nginx
  • 通过内部网络隔离 Ollama,不直接暴露模型端口
  • 配置 HTTPS、Basic Auth、请求体限制和流式代理参数
  • 使用健康检查和验证命令完成部署验收

部署目标

本课把上一课的 FastAPI 后端部署为三个服务:

text
客户端
→ HTTPS Nginx
→ 知识助手 API
→ Ollama

安全边界:

  • 只有 Nginx 映射宿主机端口。
  • 后端和 Ollama 仅在 Compose 内部网络通信。
  • Ollama 的 11434 不直接映射到公网。
  • Nginx 负责 TLS 和基础认证。
  • 模型与索引分别使用持久卷。
  • 密码文件和证书不写入镜像。

Basic Auth 适合教学与小型内网。正式多用户系统应接入统一身份、令牌、审计和权限过滤。

准备目录

在 ollama-knowledge-api 目录中创建:

bash
mkdir -p nginx certs auth data

预期结果:

text
当前目录新增 nginx、certs、auth 和 data 目录。

最终结构:

text
ollama-knowledge-api/
├── app.py
├── requirements.txt
├── Dockerfile
├── compose.yaml
├── .env
├── nginx/
│   └── default.conf
├── certs/
│   ├── fullchain.pem
│   └── privkey.pem
├── auth/
│   └── .htpasswd
└── data/

创建后端镜像

创建 Dockerfile:

dockerfile
FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

RUN useradd --create-home --uid 10001 appuser     && mkdir -p /data     && chown -R appuser:appuser /app /data

USER appuser

EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

构建行为:镜像安装依赖后以非 root 用户运行后端,索引目录挂载到 /data。

配置环境变量

创建 .env:

text
GENERATION_MODEL=<GENERATION_MODEL>
EMBEDDING_MODEL=<EMBEDDING_MODEL>
CHUNK_SIZE=700
CHUNK_OVERLAP=120
MIN_SCORE=0.25
REQUEST_TIMEOUT=180

把两个模型占位符替换为已经存在的真实模型标签。.env 不应包含长期凭证;敏感值应使用专用 Secret 管理。

编写 Compose

创建 compose.yaml:

yaml
services:
  ollama:
    image: ollama/ollama:<OLLAMA_VERSION>
    restart: unless-stopped
    volumes:
      - ollama-data:/root/.ollama
    networks:
      - backend
    healthcheck:
      test:
        - CMD
        - ollama
        - list
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 20s

  api:
    build:
      context: .
    restart: unless-stopped
    environment:
      OLLAMA_BASE_URL: http://ollama:11434
      GENERATION_MODEL: ${GENERATION_MODEL}
      EMBEDDING_MODEL: ${EMBEDDING_MODEL}
      INDEX_PATH: /data/index.json
      CHUNK_SIZE: ${CHUNK_SIZE}
      CHUNK_OVERLAP: ${CHUNK_OVERLAP}
      MIN_SCORE: ${MIN_SCORE}
      REQUEST_TIMEOUT: ${REQUEST_TIMEOUT}
    volumes:
      - knowledge-index:/data
    depends_on:
      ollama:
        condition: service_healthy
    networks:
      - backend
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - >-
          import urllib.request;
          urllib.request.urlopen(
          'http://localhost:8000/health', timeout=5)
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

  nginx:
    image: nginx:<NGINX_VERSION>
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./auth/.htpasswd:/etc/nginx/auth/.htpasswd:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - backend

networks:
  backend:
    internal: false

volumes:
  ollama-data:
  knowledge-index:

<OLLAMA_VERSION> 和 <NGINX_VERSION> 替换为已验证的固定镜像标签。这里只映射 443,Ollama 和 API 没有宿主机端口。

配置 Nginx

创建 nginx/default.conf:

nginx
server {
    listen 443 ssl;
    server_name <DOMAIN_OR_IP>;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 10m;

    auth_basic "Ollama Knowledge Assistant";
    auth_basic_user_file /etc/nginx/auth/.htpasswd;

    location / {
        proxy_pass http://api:8000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 10s;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;

        proxy_buffering off;
        proxy_request_buffering on;
    }
}

<DOMAIN_OR_IP> 替换为证书覆盖的域名。proxy_buffering off 为后续流式接口预留;当前非流式接口同样可以正常使用。

创建认证文件与证书

已安装 htpasswd 工具时创建用户:

bash
htpasswd -c auth/.htpasswd <USERNAME>

预期结果:

text
交互输入密码后,auth/.htpasswd 中生成加密凭证记录。

证书文件必须放在:

text
certs/fullchain.pem
certs/privkey.pem

正式环境使用受信任 CA 证书。测试自签名证书会让客户端需要显式信任,不应被描述为生产可信证书。

启动并准备模型

验证 Compose:

bash
docker compose config --quiet

预期结果:

text
命令正常结束且无输出,表示 YAML 和变量解析通过。

启动:

bash
docker compose up -d --build

预期输出中应包含:

text
ollama、api 和 nginx 服务被创建并启动。具体容器名称取决于项目目录。

拉取模型:

bash
docker compose exec ollama ollama pull "$GENERATION_MODEL"
docker compose exec ollama ollama pull "$EMBEDDING_MODEL"

预期结果:

text
两个模型完成下载;若模型已经存在,命令会验证或复用本地数据。

验证安全边界

查看端口:

bash
docker compose ps
docker compose port nginx 443

预期结果:

text
只有 nginx 映射宿主机 443;api 和 ollama 不显示宿主机公开端口。

未带认证请求:

bash
curl --insecure --silent --output /dev/null   --write-out "%{http_code}
" https://<DOMAIN_OR_IP>/health

预期输出:

text
401

带认证请求:

bash
curl --insecure --user '<USERNAME>:<PASSWORD>'   https://<DOMAIN_OR_IP>/health

预期 HTTP 结果:

text
状态码 200,响应包含 status、ollama_status、generation_model 和 embedding_model。

--insecure 只用于尚未建立信任的测试证书;正式证书应移除该参数。

上线前的安全补充

Basic Auth 之外还应评估:

  • 用户级权限与文档来源过滤
  • API Token 生命周期
  • 密码和证书轮换
  • 请求频率限制
  • 上传大小和内容类型限制
  • 访问日志脱敏
  • 依赖镜像漏洞扫描
  • 容器只读文件系统和最小权限
  • 主机防火墙
  • 备份加密
  • 管理接口与业务接口分离

反向代理保护的是入口,不能代替后端对文档权限和输入内容的校验。

本课练习

练习 1:完成三服务部署

任务目标:运行 Ollama、API 和 Nginx。输入或初始条件:已完成上一课代码并准备两个模型。实现要求:按 Compose 启动并检查健康状态。验收条件:三个服务健康,只有 443 映射宿主机。

练习 2:验证认证边界

任务目标:确认匿名请求无法访问。输入或初始条件:已生成密码文件和测试证书。实现要求:分别发送匿名与认证请求。验收条件:匿名返回 401,认证请求返回 200。

练习 3:验证持久化

任务目标:确认容器重建后模型和索引保留。输入或初始条件:已导入文档并下载模型。

实现要求:执行 docker compose down 后重新启动。验收条件:模型列表和知识索引仍存在。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

部署并保护项目接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通