📖 本章学习目标
- 编写多阶段 Dockerfile 和 Docker Compose 编排 RAG 服务、向量数据库与缓存中间件
- 在 CI/CD 流水线中自动检测文档变更并触发索引重建,区分开发环境与生产环境的配置策略
- 设计蓝绿部署方案,实现部署过程中的零停机切换和秒级回滚
- 建立索引版本管理机制,在检索质量下降时快速回退到稳定版本
引言:从性能达标到稳定上线
流式输出和 Embedding 批处理做完之后,系统在单机上的延迟和成本已经优化到可接受的范围。但这些优化都在开发环境中验证的,要让用户真正用上,还需要解决的最后一个工程问题就是如何将系统可靠地交付到服务器上,并保证后续的更新不影响正在运行的服务。
部署不是把代码拷到服务器上然后启动。生产环境需要考虑容器化消除环境差异、CI/CD 自动化构建和测试、部署过程中的零停机切换、以及新版本出问题时能快速回退。这些问题互相关联,任何一个环节的疏漏都可能导致线上故障。本章按交付链路的顺序逐一讨论。
一、Docker 容器化
开发环境和生产环境之间的差异是最常见的部署问题来源。Node.js 版本不一致、系统库缺失、依赖路径不同,都可能导致开发环境正常运行而生产环境报错。容器化将应用及其所有依赖打包为一个可移植的镜像,在任何安装了 Docker 的机器上都能以相同的方式运行。
1. 多阶段构建
多阶段构建将编译过程和运行环境分离。构建阶段安装全部依赖并编译 TypeScript,运行阶段只复制编译产物和生产依赖。最终镜像的大小通常能缩减到单阶段构建的三分之一以下,而且不包含 devDependencies 中的工具链,减少了安全攻击面。
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine AS runner
WORKDIR /app
RUN apk add --no-cache curl
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
USER nodejs
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]
关键点在于 USER nodejs 让进程以非 root 权限运行,即使应用被攻破,攻击者的操作范围也受限。HEALTHCHECK 指令让 Docker 能自动检测容器是否健康,配合编排工具的 depends_on 可以控制服务启动顺序。
2. 服务编排
RAG 系统通常需要三个以上的服务配合运行:API 服务、向量数据库和缓存中间件。Docker Compose 用一个 YAML 文件声明所有服务及其依赖关系,一条命令即可启动整个技术栈。下面只展示 RAG API 服务的定义,Chroma 和 Redis 的配置模式类似。
services:
rag-api:
build:
context: .
dockerfile: Dockerfile
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- OPENAI_API_KEY=${OPENAI_API_KEY}
- CHROMA_URL=http://chroma:8000
- REDIS_URL=redis://redis:6379
depends_on:
chroma:
condition: service_healthy
redis:
condition: service_healthy
restart: unless-stopped
deploy:
resources:
limits:
memory: 1G
cpus: '1.0'
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
depends_on 配合 condition: service_healthy 确保 Chroma 和 Redis 的健康检查通过后才启动 API 服务,避免了启动顺序导致的连接失败。restart: unless-stopped 确保服务崩溃后自动恢复。deploy.resources.limits 设定了资源上限,防止某个服务在异常情况下耗尽宿主机资源。
3. 开发与生产环境分离
开发环境需要热重载、源代码挂载和详细的错误日志,生产环境需要预构建的镜像、多副本部署和资源限制。用两个 Compose 文件分别声明这些差异,比在一个文件里用条件判断更清晰。
开发环境的关键差异是将源代码目录挂载到容器内并覆盖启动命令为热重载模式:
services:
rag-api:
build:
dockerfile: Dockerfile.dev
volumes:
- .:/app
- /app/node_modules
environment:
- NODE_ENV=development
command: npm run dev
生产环境则使用预构建镜像,声明副本数和滚动更新策略:
services:
rag-api:
image: myregistry.com/rag-api:latest
environment:
- NODE_ENV=production
deploy:
replicas: 3
update_config:
parallelism: 1
delay: 10s
启动时通过 -f 参数选择对应的文件:开发用 docker compose -f docker-compose.dev.yml up,生产用 docker compose -f docker-compose.prod.yml up -d。两个文件共享相同的服务名称和网络配置,只是运行参数不同。
二、CI/CD 流水线
上一节解决了运行环境的一致性问题,但部署流程本身还需要自动化。手动部署存在三个风险:步骤遗漏导致配置不完整、每次部署流程略有不同导致不可复现、出现问题后没有版本记录可供回滚。CI/CD 将构建、测试和部署流程固化为配置文件,每次代码推送自动执行,消除了手工操作的不确定性。
1. 代码提交时自动测试
每次 push 到主分支或提交 PR 时自动运行 lint、测试和构建,确保不会因为遗漏而合入未通过检查的代码。
name: Test
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
services:
redis:
image: redis:7-alpine
ports:
- 6379:6379
options: >-
--health-cmd "redis-cli ping"
--health-interval 10s
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run tests
run: npm test
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
- name: Build
run: npm run build
CI 流水线中通过 services 声明了 Redis 测试依赖,GitHub Actions 会在 job 运行期间启动一个 Redis 容器并自动注入网络配置,测试完成后自动销毁。生产环境的 Chroma 和 Pinecone 等外部服务不需要在 CI 中启动,测试代码应使用 mock 或专用的测试实例。
2. 文档变更自动重建索引
知识库文档更新后,向量索引必须同步更新。与其让人记住手动执行重建脚本,不如让 CI 在检测到文档目录变更时自动触发。下面的工作流监听了 docs/** 和 knowledge-base/** 两个路径的 push 事件:
name: Rebuild Index
on:
push:
paths:
- "docs/**"
- "knowledge-base/**"
branches: [main]
jobs:
reindex:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Rebuild Index
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
CHROMA_URL: ${{ secrets.CHROMA_URL }}
run: npx tsx scripts/rebuild-index.ts --namespace production
paths 过滤器确保只有文档目录的变更才会触发索引重建,代码重构或配置修改不会浪费 CI 资源去重建索引。
3. 索引重建的核心流程
索引重建不是简单地覆盖旧数据。如果重建过程中服务仍在接收查询,用户可能搜到不完整的索引。安全的做法是创建新索引、验证完整性、原子切换、再清理旧版本。下面将重建脚本拆分为类型定义、主流程和辅助函数三个部分。
类型定义和主流程入口:
interface RebuildOptions {
namespace: string;
docsPath: string;
batchSize: number;
}
async function rebuildIndex(options: RebuildOptions): Promise<void> {
const { namespace, docsPath, batchSize = 100 } = options;
const startTime = Date.now();
const client = new ChromaClient({
path: process.env.CHROMA_URL || "http://localhost:8000",
});
const docs = await loadAndSplitDocuments(docsPath);
if (docs.length === 0) {
throw new Error("没有文档需要索引");
}
const versionName = `knowledge_base_${namespace}_v${Date.now()}`;
const collection = await client.createCollection({
name: versionName,
metadata: {
created_at: new Date().toISOString(),
namespace,
},
});
批量索引与验证:
let indexedCount = 0;
for (let i = 0; i < docs.length; i += batchSize) {
const batch = docs.slice(i, i + batchSize);
const texts = batch.map(d => d.pageContent);
const embeddings = await embedBatch(texts);
await collection.add({
ids: batch.map((_, idx) => `doc_${i + idx}`),
embeddings,
documents: texts,
metadatas: batch.map(d => d.metadata),
});
indexedCount += batch.length;
}
const testEmbedding = await embedBatch(["验证查询"]);
const results = await collection.query({
queryEmbeddings: testEmbedding,
nResults: 1,
});
if (results.documents[0].length === 0) {
throw new Error("索引验证失败:无法检索到文档");
}
别名切换与旧版本清理:
await updateAlias(namespace, versionName);
await cleanupOldVersions(client, namespace, 5);
const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
return { versionName, indexedCount, totalTime };
}
updateAlias 的核心操作是在 Redis 中更新一个 key,指向新的索引名称。应用层每次查询时先读取这个 key 获取当前活跃的索引名,再向对应的 Collection 发起检索。这个间接层是实现索引切换和回滚的基础。
清理逻辑按版本号降序排列,保留最近的 N 个版本,删除其余。保留多少版本取决于存储空间和回滚需求,通常保留 3 到 5 个即可覆盖绝大多数回滚场景。
三、蓝绿部署
容器化和 CI/CD 解决了构建和测试的自动化,但部署到线上还有一个关键问题,即如何在不停服务的情况下切换到新版本。传统部署直接停掉旧服务再启动新服务,中间存在几十秒到几分钟的不可用窗口。蓝绿部署通过同时运行新旧两套环境,切换只在负载均衡层面完成,用户无感知。
graph LR
A[负载均衡] -->|当前流量| B[蓝环境 v1.0]
A -. "切换后" .-> C[绿环境 v2.0]
1. 部署流程
蓝绿部署的执行顺序是先在空闲的绿环境中启动新版本并完成全部检查,确认无误后将负载均衡的流量指向绿环境,蓝环境保留一段时间作为回退的保险。
Nginx 的 upstream 配置是实现流量切换的常见方式:
upstream blue {
server rag-api-blue:3000;
}
upstream green {
server rag-api-green:3000;
}
server {
listen 80;
location / {
proxy_pass http://blue;
}
}
将 proxy_pass 的目标从 blue 改为 green 然后重载 Nginx,流量切换在秒级完成。
2. 部署脚本的核心逻辑
部署脚本不需要覆盖所有边缘情况,但需要明确每一步的成功标准和失败行为。下面的代码提取了核心状态机,省略了 HTTP 请求和 shell 调用的实现细节。
async function deployBlueGreen(version: string): Promise<void> {
const currentEnv = await getCurrentEnv();
const targetEnv = currentEnv === "blue" ? "green" : "blue";
await deployToEnv(targetEnv, version);
const healthy = await healthCheck(targetEnv);
if (!healthy) {
throw new Error(`${targetEnv} 环境健康检查失败`);
}
const testsPassed = await runIntegrationTests(targetEnv);
if (!testsPassed) {
throw new Error(`${targetEnv} 集成测试失败`);
}
await switchTraffic(targetEnv);
await monitor(targetEnv, 60);
}
每个步骤抛出的错误都会被外层的 try-catch 捕获并触发自动回滚。健康检查会在 50 秒内以 5 秒间隔重试,给服务启动留出足够的时间。集成测试至少包含一次完整的查询请求,验证 Embedding 生成、向量检索和 LLM 调用三个环节都能正常连通。
3. 监控与回滚
切换流量后需要观察错误率和延迟一小段时间。这段时间不需要多长,但必须覆盖大多数请求的生命周期。如果指标超出预设阈值,立即将流量切回旧环境:
async function rollback(): Promise<void> {
const currentEnv = await getCurrentEnv();
const previousEnv = currentEnv === "blue" ? "green" : "blue";
await switchTraffic(previousEnv);
}
回滚操作本身和执行顺序无关,只需要调用相同的流量切换函数。这里不尝试回滚数据库 schema 或文件系统状态,那些操作应该在部署设计阶段就保证向后兼容。
四、索引版本管理
蓝绿部署解决了代码版本的回滚,但 RAG 系统还有另一个需要独立回滚的组件:向量索引。索引的质量取决于切分策略、Embedding 模型和源文档内容,这些因素的变更可能导致检索质量下降,即使 API 代码本身没有问题。
1. 版本标识与别名映射
索引版本管理通过一个间接层实现:每个索引有独立的名称(包含时间戳),应用通过一个别名查找当前活跃的版本。这个别名存储在 Redis 中,所有查询请求共享同一个映射。
class IndexVersionManager {
private namespace: string;
constructor(namespace: string) {
this.namespace = namespace;
}
async listVersions(): Promise<Array<{
name: string;
docCount: number;
createdAt: string;
}>> {
const client = new ChromaClient({
path: process.env.CHROMA_URL || "http://localhost:8000",
});
const collections = await client.listCollections();
const pattern = new RegExp(
`^knowledge_base_${this.namespace}_v\\d+$`
);
const versions = await Promise.all(
collections
.filter(c => pattern.test(c.name))
.map(async c => {
const collection = await client.getCollection({ name: c.name });
const count = await collection.count();
return {
name: c.name,
createdAt: c.metadata?.created_at || "unknown",
docCount: count,
};
})
);
return versions.sort((a, b) => {
const va = parseInt(a.name.split('_v')[1]);
const vb = parseInt(b.name.split('_v')[1]);
return vb - va;
});
}
数据查询方法是获取当前别名映射和切换到指定版本:
async getCurrentVersion(): Promise<string> {
const redis = new Redis(process.env.REDIS_URL);
const key = `rag:index:alias:${this.namespace}`;
const version = await redis.get(key);
await redis.quit();
return version || `knowledge_base_${this.namespace}_v0`;
}
async switchToVersion(versionName: string): Promise<void> {
const redis = new Redis(process.env.REDIS_URL);
const key = `rag:index:alias:${this.namespace}`;
await redis.set(key, versionName);
await redis.quit();
}
}
2. 回滚决策
索引回滚的触发条件不是硬编码的阈值,而是来自监控系统的信号。第19章会建立检索质量的持续监测机制,包括 MRR 的波动、空结果率的变化和用户的负面反馈。当监测到这些指标的异常波动时,通过上一节的 switchToVersion 方法一步切回上一个稳定版本。
索引回滚只影响新查询。已经生成的答案和它们引用的文档不受回滚影响,回滚不会修改历史数据。保留最近几个版本(通常是 3 到 5 个)即可覆盖绝大多数回滚需求,更早的版本在存储空间紧张时可以清理。
五、部署检查清单
部署到生产环境之前,应该逐一确认以下事项。这些条目不是一次性的,每次部署前都需要验证。
| 检查类别 | 关键条目 |
|---|---|
| 代码质量 | 全部测试通过,代码审查完成,安全扫描无高危漏洞 |
| 镜像与配置 | 镜像构建成功并推送到 Registry,环境变量和密钥已更新,数据库和缓存连接正常 |
| 监控告警 | 日志收集已配置,Dashboard 面板可用,告警规则已验证,健康检查端点暴露 |
| 应急预案 | 回滚脚本已测试通过,数据已备份,应急联系人已明确,回滚决策的触发条件已文档化 |
这个清单的目的是在部署前主动发现问题,而不是在部署后被动处理事故。每次部署后如果触发了清单之外的问题,就把新的检查项补充进来。
FAQ
Q1:索引重建需要多长时间?
取决于文档数量、文本长度和 Embedding API 的速率限制。主要的时间消耗在 Embedding 批量生成而不是文档切分或向量插入。对于中等规模的知识库(数千篇文档),通常在数分钟内完成。大规模知识库建议复用第16章的异步索引管道,不要在 CI 流水线中执行全量重建。
Q2:蓝绿部署需要两套向量数据库吗?
取决于数据库的隔离机制。Pinecone 可在同一个 Index 内使用不同的 Namespace 实现隔离。Chroma 需要创建两个独立的 Collection。关键是新旧索引不能共享同一个存储空间,否则切换和回滚无法做到原子性。如果数据库本身不支持多版本隔离,就需要在应用层通过别名机制(如 Redis key 映射)来实现,如本章第四节所述。
Q3:如何处理部署期间的写入请求?
如果系统支持文档上传和实时索引,部署期间需要决定写入请求的去向。两种常见做法:只读模式在部署期间拒绝写请求,部署完成后恢复,实现简单;双写模式同时写入新旧两个环境,部署完成后停止向旧环境写入,复杂度高但零中断。推荐从只读模式起步,除非业务对部署期间的写入可用性有硬性要求。
Q4:如何验证部署是否成功?
健康检查通过只是第一步。完整的验证包括运行一组标准查询并对比部署前后的答案质量、检查错误率和延迟的监控曲线是否有突增、人工抽检若干真实问题确认答案的完整性和引用准确性。不建议只依赖健康检查的 HTTP 200 状态码来判定部署成功。
练习
练习 1:为你的 RAG 项目编写 Dockerfile 和 Compose 文件
基于第7章或第16章的项目代码,编写多阶段 Dockerfile 和 docker-compose.yml。用 docker compose up 启动完整服务并验证 /health 端点返回正常状态。
验证步骤:
- 构建镜像并启动全部服务
- 执行
curl http://localhost:3000/health,确认返回状态正常 - 发送一条真实查询,验证 Embedding、检索和生成三个环节都能正常连通
- 检查容器日志,确认没有启动阶段的连接错误
预期结果:所有服务正常运行,能够执行完整的 RAG 查询流程,查询结果符合预期。
练习 2:实现索引版本管理
编写脚本实现"新建索引并验证后原子切换别名"的流程。手动运行两次(模拟两次文档更新),验证别名始终指向最新版本,并且旧版本仍然存在可供回滚。
验证步骤:
- 创建一个初始索引,并设置别名为当前版本
- 更新文档内容后运行重建脚本,自动创建新版本并切换别名
- 通过别名查询,确认返回的是新版本的数据
- 列出所有版本,手动切回旧版本,确认查询结果正确还原
预期结果:别名始终指向最新索引,可随时通过版本管理接口回退到任意历史版本。
练习 3:容器化部署并测试回滚流程
在本机用 Docker Compose 模拟一次蓝绿部署,先启动 v1.0 作为蓝环境,再启动 v2.0 作为绿环境,切换流量后验证新版本生效,然后回滚。
验证步骤:
- 启动蓝环境(标签为 v1.0),确认服务正常
- 在绿环境中启动更新后的镜像(标签为 v2.0)
- 对绿环境执行健康检查和基础查询测试
- 将流量切换到绿环境,验证新版本生效
- 模拟发现问题后执行回滚到蓝环境
预期结果:流量切换在秒级完成,切换过程中无请求失败,回滚后恢复到 v1.0 的状态。
练习 4:配置 CI/CD 流水线
为项目配置 GitHub Actions 工作流,实现代码推送后自动运行测试和构建,文档变更后自动触发索引重建。
验证步骤:
- 推送代码变更,观察 CI 自动运行测试和构建
- 推送文档目录的变更,观察索引重建工作流被触发
- 推送非文档目录的变更,确认索引重建未被误触发
- 检查工作流日志,确认每一步都正常完成
预期结果:代码变更自动触发测试流水线,文档变更自动触发索引重建,两者互不干扰。
📚 延伸阅读
- Docker Compose Documentation — Docker Compose 官方文档,包含详细的使用示例
- GitHub Actions Documentation — GitHub Actions CI/CD 官方文档
- Blue-Green Deployment — Martin Fowler 的蓝绿部署经典文章,深入讲解部署策略
- Docker Best Practices — Docker 最佳实践指南
- Kubernetes Deployment Strategies — Kubernetes 部署策略文档,适合大规模生产环境