大模型应用开发 / 系统课时
部署并保护项目接口
部署并保护项目接口
学习目标
完成本课后,你将能够:
- 使用 Docker Compose 编排 Ollama、知识助手后端和 Nginx
- 通过内部网络隔离 Ollama,不直接暴露模型端口
- 配置 HTTPS、Basic Auth、请求体限制和流式代理参数
- 使用健康检查和验证命令完成部署验收
部署目标
本课把上一课的 FastAPI 后端部署为三个服务:
客户端
→ HTTPS Nginx
→ 知识助手 API
→ Ollama安全边界:
- 只有 Nginx 映射宿主机端口。
- 后端和 Ollama 仅在 Compose 内部网络通信。
- Ollama 的
11434不直接映射到公网。 - Nginx 负责 TLS 和基础认证。
- 模型与索引分别使用持久卷。
- 密码文件和证书不写入镜像。
Basic Auth 适合教学与小型内网。正式多用户系统应接入统一身份、令牌、审计和权限过滤。
准备目录
在 ollama-knowledge-api 目录中创建:
mkdir -p nginx certs auth data预期结果:
当前目录新增 nginx、certs、auth 和 data 目录。最终结构:
ollama-knowledge-api/
├── app.py
├── requirements.txt
├── Dockerfile
├── compose.yaml
├── .env
├── nginx/
│ └── default.conf
├── certs/
│ ├── fullchain.pem
│ └── privkey.pem
├── auth/
│ └── .htpasswd
└── data/创建后端镜像
创建 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:
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:
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:
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 工具时创建用户:
htpasswd -c auth/.htpasswd <USERNAME>预期结果:
交互输入密码后,auth/.htpasswd 中生成加密凭证记录。证书文件必须放在:
certs/fullchain.pem
certs/privkey.pem正式环境使用受信任 CA 证书。测试自签名证书会让客户端需要显式信任,不应被描述为生产可信证书。
启动并准备模型
验证 Compose:
docker compose config --quiet预期结果:
命令正常结束且无输出,表示 YAML 和变量解析通过。启动:
docker compose up -d --build预期输出中应包含:
ollama、api 和 nginx 服务被创建并启动。具体容器名称取决于项目目录。拉取模型:
docker compose exec ollama ollama pull "$GENERATION_MODEL"
docker compose exec ollama ollama pull "$EMBEDDING_MODEL"预期结果:
两个模型完成下载;若模型已经存在,命令会验证或复用本地数据。验证安全边界
查看端口:
docker compose ps
docker compose port nginx 443预期结果:
只有 nginx 映射宿主机 443;api 和 ollama 不显示宿主机公开端口。未带认证请求:
curl --insecure --silent --output /dev/null --write-out "%{http_code}
" https://<DOMAIN_OR_IP>/health预期输出:
401带认证请求:
curl --insecure --user '<USERNAME>:<PASSWORD>' https://<DOMAIN_OR_IP>/health预期 HTTP 结果:
状态码 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 后重新启动。验收条件:模型列表和知识索引仍存在。