环境配置

概述¶

本指南介绍 RAG（检索增强生成）系统的完整环境搭建流程，包括所需环境变量、API 密钥配置及部署设置。

必需环境变量¶

RAG 系统在内容上传和运行前需设置若干环境变量。这些变量会被 Makefile 目标和各类脚本校验和使用。

核心配置变量¶

变量名	说明	是否必需	示例值
`ADMIN_TOKEN`	Cloudflare API Token，用于认证	✅ 必需	`your-cloudflare-api-token`
`WORKER_URL`	RAG Worker 部署地址	✅ 必需	`https://website-rag-worker.jimmysong.io`
`PROVIDER`	AI 服务商（用于嵌入和生成）	✅ 必需	`qwen` 或 `gemini`
`QWEN_API_KEY`	阿里云 Qwen API 密钥	✅ 必需*	`sk-your-qwen-api-key`
`GOOGLE_API_KEY`	Google AI API 密钥	✅ 必需*	`your-google-api-key`

* 根据 PROVIDER 设置决定是否必需

可选配置变量¶

变量名	说明	默认值
`QWEN_BASE`	Qwen API 基础地址	`https://dashscope.aliyuncs.com/compatible-mode/v1`
`QWEN_EMBED_MODEL`	Qwen 嵌入模型	`text-embedding-v4`
`LLM_MODEL`	生成用语言模型	`qwen-turbo-latest`
`EMBED_DIM`	向量维度	`1024`

步骤详解¶

1. 环境变量配置¶

方案 A：Shell 配置文件（推荐）¶

将以下内容添加到你的 shell 配置文件（如 ~/.zshrc、~/.bashrc）：

# RAG 系统环境变量
export WORKER_URL=https://website-rag-worker.jimmysong.io
export ADMIN_TOKEN=your-cloudflare-api-token
export PROVIDER=qwen
export QWEN_API_KEY=your-qwen-api-key

# 可选配置
export QWEN_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
export QWEN_EMBED_MODEL=text-embedding-v4
export LLM_MODEL=qwen-turbo-latest
export EMBED_DIM=1024

然后重载 shell：

source ~/.zshrc  # 或 ~/.bashrc

方案 B：当前会话临时设置¶

仅在当前会话设置变量：

export WORKER_URL=https://website-rag-worker.jimmysong.io
export ADMIN_TOKEN=your-cloudflare-api-token
export PROVIDER=qwen
export QWEN_API_KEY=your-qwen-api-key

方案 C：.env 文件配置¶

在 RAG worker 目录下创建 .env 文件：

cd tools/rag-worker
cat > .env << EOF
WORKER_URL=https://website-rag-worker.jimmysong.io
ADMIN_TOKEN=your-cloudflare-api-token
PROVIDER=qwen
QWEN_API_KEY=your-qwen-api-key
EOF

2. 获取所需 API 密钥¶

Cloudflare API Token (ADMIN_TOKEN)¶

访问 Cloudflare 控制台
点击“创建 Token”
选择“自定义 token”模板
配置权限：
Account: Cloudflare Workers:Edit
Zone: Zone:Read
Zone Resources: 包含所有或指定 zone
为 R2 添加权限：
Account: Cloudflare R2:Edit
复制生成的 token

Qwen API 密钥（QWEN_API_KEY）¶

访问阿里云 DashScope
注册或登录账号
进入 API Key 管理
新建 API Key
复制 API Key（格式如：sk-xxxxxxxxxxxx）

Google AI API 密钥（GOOGLE_API_KEY）¶

访问 Google AI Studio
新建 API Key
复制 API Key

3. 验证环境配置¶

验证环境变量：

# 检查变量是否设置
echo "WORKER_URL: $WORKER_URL"
echo "ADMIN_TOKEN: $ADMIN_TOKEN"
echo "PROVIDER: $PROVIDER"
echo "QWEN_API_KEY: $QWEN_API_KEY"

# 测试 RAG 系统连通性
cd /path/to/your/website
make rag-test

可用 Makefile 目标¶

环境变量配置完成后，可使用如下 Makefile 命令：

内容上传命令¶

# 上传单个文件
make rag-upload FILE=content/zh/blog/my-article/index.md

# 上传整个目录
make rag-upload-dir DIR=content/zh/blog

# 批量上传多个目录
make rag-upload-batch DIRS='content/zh/book content/en/docs'

# 快速批量导入
make rag-fast-ingest

配置管理¶

# 上传外部配置到 R2
make rag-upload-config

# 部署 RAG worker
make rag-deploy

测试与验证¶

# 测试 RAG 系统组件
make rag-test

# 验证向量数据完整性
make rag-verify

# 重新索引所有向量数据
make rag-reindex

架构配置¶

Worker 配置（wrangler.toml）¶

RAG worker 通过 tools/rag-worker/wrangler.toml 配置：

name = "website-rag-worker"
main = "src/worker.ts"
compatibility_date = "2024-07-01"

# 自定义域名
routes = [
  { pattern = "website-rag-worker.jimmysong.io", custom_domain = true }
]

[vars]
PROVIDER = "qwen"
EMBED_DIM = 1024
LLM_MODEL = "qwen-turbo-latest"
QWEN_EMBED_MODEL = "text-embedding-v4"

[[vectorize]]
binding = "VECTORIZE"
index_name = "website-rag"

[[r2_buckets]]
binding = "CONFIG_BUCKET"
bucket_name = "website-rag-config"
preview_bucket_name = "website-rag-config-preview"

环境变量校验¶

Makefile 在执行 RAG 操作前会校验必需环境变量：

# Makefile 环境检查示例
@if [ -z "$$ADMIN_TOKEN" ] || [ -z "$$WORKER_URL" ]; then \
    echo "错误: 缺少必要的环境变量 ADMIN_TOKEN 和 WORKER_URL"; \
    echo "请设置环境变量后重试"; \
    exit 1; \
fi

故障排查¶

常见问题¶

缺少环境变量 - 环境配置不完整：
```
Error: 缺少必要的环境变量 ADMIN_TOKEN 和 WORKER_URL
```
解决方法：按上述方法设置环境变量。
API 密钥无效 - 认证失败：
```
Error: Authentication failed
```
解决方法：检查 API 密钥是否正确且权限充足。
网络连接异常 - Worker 连接失败：
```
Error: Failed to connect to worker
```
解决方法：确认 WORKER_URL 正确且 worker 已部署。

调试命令¶

# 检查环境变量
env | grep -E "(ADMIN_TOKEN|WORKER_URL|PROVIDER|QWEN_API_KEY)"

# 测试 API 连通性
curl -H "Authorization: Bearer $ADMIN_TOKEN" "$WORKER_URL/admin/health"

# 检查 Cloudflare tunnel 状态
cloudflared tunnel list

# 验证 wrangler 认证
npx wrangler whoami

安全建议¶

API 密钥保护：切勿将密钥提交到版本控制
环境隔离：开发与生产环境使用不同密钥
Token 定期轮换：定期更换 API Token
权限最小化：API Token 仅授予必要权限

后续步骤¶

环境搭建完成后：

部署 Worker：make rag-deploy
上传配置：make rag-upload-config
内容入库：make rag-upload-dir DIR=content/zh/blog
系统测试：make rag-test