Haitao Pan 82c0cae4e2 feat: update homepage tagline and tech stack

- Update tagline to emphasize cloud-native, vendor-neutral architecture
  - 🇨🇳 Chinese: 云原生 · 去平台绑定 · 可自由迁移
  - 🇺🇸 English: Cloud-native · Vendor-neutral · Freely portable
- Replace tech stack logos: Next.js, Go, Vercel, Cloud Run, PostgreSQL
- Remove outdated stack references (Vue, Svelte, Node, Django, Laravel)

2026-01-26 15:49:56 +08:00

5.7 KiB

Raw Blame History

RAG Server 数据库连接修复 Runbook

📋 概述

问题: RAG Server 无法连接到 PostgreSQL 数据库，导致 /api/rag/query 返回 404
影响范围: RAG 检索功能、向量搜索、知识库同步
修复时间: ~5 分钟
风险等级: 🟡 中等（前端已实现降级，用户体验影响有限）

🔍 问题诊断

错误症状

ERROR: cannot parse `admin_password`: failed to parse as keyword/value (invalid keyword/value)
WARN: postgres cache disabled; no database connection

根本原因

❌ DATABASE_URL 环境变量指向 Secret Manager 引用 admin_password，而不是实际的数据库连接字符串
❌ RAG 服务器无法连接到 PostgreSQL 数据库
❌ 导致 /api/rag/query 返回 404

架构图

┌─────────────────────┐
│  Cloud Run          │
│  (RAG Server)       │
└──────────┬──────────┘
           │
           ↓
┌─────────────────────┐
│  Stunnel            │
│  127.0.0.1:5432     │
└──────────┬──────────┘
           │ TLS Tunnel
           ↓
┌─────────────────────┐
│  postgresql         │
│  .onwalk.net:443    │
└──────────┬──────────┘
           │
           ↓
┌─────────────────────┐
│  PostgreSQL         │
│  Database           │
└─────────────────────┘

✅ 修复方案

方案 1: 使用 Stunnel (推荐) ⭐

优势

✅ 安全性更好（TLS 加密）
✅ 不需要暴露数据库公网 IP
✅ 符合现有架构设计
✅ entrypoint.sh 已经支持 Stunnel

步骤 1: 更新 Cloud Run 环境变量

gcloud run services update rag-server-svc-plus \
  --region asia-northeast1 \
  --project xzerolab-480008 \
  --update-env-vars="\
DB_TLS_HOST=postgresql.onwalk.net,\
DB_TLS_PORT=443,\
POSTGRES_USER=postgres,\
POSTGRES_PASSWORD=otdcRLTJamszk3AE,\
POSTGRES_DB=knowledge_db,\
NVIDIA_API_KEY=NVAPI_KEY_PLACEHOLDER" \
  --clear-env-vars=DATABASE_URL

关键参数说明:

DB_TLS_HOST 和 DB_TLS_PORT: 触发 entrypoint.sh 启动 Stunnel
Stunnel 会在 127.0.0.1:5432 监听
config/rag-server.yaml 中的 pgurl 会自动使用 127.0.0.1:5432
--clear-env-vars=DATABASE_URL: 移除错误的环境变量

步骤 2: 验证部署

检查日志:

gcloud logging read \
  "resource.type=cloud_run_revision AND resource.labels.service_name=rag-server-svc-plus" \
  --limit 20 \
  --project xzerolab-480008 \
  --format="table(timestamp,textPayload)"

期望输出:

Starting Stunnel...
Stunnel is up!
INFO: Connected to PostgreSQL at 127.0.0.1:5432

步骤 3: 功能测试

测试 RAG 查询:

curl -X POST https://rag-server-svc-plus-HASH-an.a.run.app/api/rag/query \
  -H "Content-Type: application/json" \
  -d '{"query": "test query", "top_k": 5}'

期望响应: HTTP 200，包含检索结果

方案 2: 直接数据库连接 (不推荐)

⚠️ 仅在 PostgreSQL 有公网 IP 且无法使用 Stunnel 时使用

# 更新 Secret Manager
echo "postgres://postgres:otdcRLTJamszk3AE@<PUBLIC_IP>:5432/knowledge_db?sslmode=require" | \
  gcloud secrets versions add DATABASE_URL --data-file=- --project xzerolab-480008

# 更新 Cloud Run 使用 Secret
gcloud run services update rag-server-svc-plus \
  --region asia-northeast1 \
  --project xzerolab-480008 \
  --update-secrets=DATABASE_URL=DATABASE_URL:latest

📊 当前状态

✅ 工作的功能

/api/askai - 直接 AI 回答（不依赖数据库）
CORS 配置
NVIDIA API 集成

❌ 待修复的功能

/api/rag/query - RAG 检索（需要数据库连接）
向量搜索
知识库同步

🎯 前端降级策略

前端已经实现了优雅降级：

首选: 尝试 /api/rag/query (RAG 检索)
降级: 如果失败，回退到 /api/askai (直接 AI)
结果: 用户仍然可以获得答案，只是没有知识库上下文

🔄 回滚计划

如果修复后出现问题，执行以下回滚：

# 恢复原有 DATABASE_URL
gcloud run services update rag-server-svc-plus \
  --region asia-northeast1 \
  --project xzerolab-480008 \
  --update-secrets=DATABASE_URL=admin_password:latest \
  --remove-env-vars=DB_TLS_HOST,DB_TLS_PORT,POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_DB

📝 验证清单

Cloud Run 环境变量已更新
DATABASE_URL 已清除
日志显示 "Stunnel is up!"
/api/rag/query 返回 200
前端 RAG 功能正常
向量搜索可用

📚 相关文档

🆘 故障排查

问题: Stunnel 无法启动

检查:

# 查看 Stunnel 日志
gcloud logging read "textPayload=~\"stunnel\"" --limit 50 --project xzerolab-480008

可能原因:

DNS 解析失败
防火墙阻止 443 端口
证书验证失败

问题: 数据库连接超时

检查:

# 测试网络连通性
gcloud run services describe rag-server-svc-plus \
  --region asia-northeast1 \
  --project xzerolab-480008 \
  --format="value(status.url)"