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)
This commit is contained in:
Haitao Pan
parent
3ca81b7194
commit
82c0cae4e2
230
Runbook/RAG-DB-Fixed.md
Normal file
230
Runbook/RAG-DB-Fixed.md
Normal file
@ -0,0 +1,230 @@
|
|||||||
|
# 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
|
||||||
|
```
|
||||||
|
|
||||||
|
### 根本原因
|
||||||
|
|
||||||
|
1. ❌ `DATABASE_URL` 环境变量指向 Secret Manager 引用 `admin_password`，而不是实际的数据库连接字符串
|
||||||
|
2. ❌ RAG 服务器无法连接到 PostgreSQL 数据库
|
||||||
|
3. ❌ 导致 `/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 环境变量
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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: 验证部署
|
||||||
|
|
||||||
|
**检查日志**:
|
||||||
|
```bash
|
||||||
|
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 查询**:
|
||||||
|
```bash
|
||||||
|
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 时使用**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 更新 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 检索（需要数据库连接）
|
||||||
|
- 向量搜索
|
||||||
|
- 知识库同步
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 前端降级策略
|
||||||
|
|
||||||
|
前端已经实现了优雅降级：
|
||||||
|
|
||||||
|
1. **首选**: 尝试 `/api/rag/query` (RAG 检索)
|
||||||
|
2. **降级**: 如果失败，回退到 `/api/askai` (直接 AI)
|
||||||
|
3. **结果**: 用户仍然可以获得答案，只是没有知识库上下文
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 回滚计划
|
||||||
|
|
||||||
|
如果修复后出现问题，执行以下回滚：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 恢复原有 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 配置文档](../docs/stunnel-setup.md)
|
||||||
|
- [PostgreSQL 连接指南](../docs/postgres-connection.md)
|
||||||
|
- [Cloud Run 环境变量管理](https://cloud.google.com/run/docs/configuring/environment-variables)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🆘 故障排查
|
||||||
|
|
||||||
|
### 问题: Stunnel 无法启动
|
||||||
|
|
||||||
|
**检查**:
|
||||||
|
```bash
|
||||||
|
# 查看 Stunnel 日志
|
||||||
|
gcloud logging read "textPayload=~\"stunnel\"" --limit 50 --project xzerolab-480008
|
||||||
|
```
|
||||||
|
|
||||||
|
**可能原因**:
|
||||||
|
- DNS 解析失败
|
||||||
|
- 防火墙阻止 443 端口
|
||||||
|
- 证书验证失败
|
||||||
|
|
||||||
|
### 问题: 数据库连接超时
|
||||||
|
|
||||||
|
**检查**:
|
||||||
|
```bash
|
||||||
|
# 测试网络连通性
|
||||||
|
gcloud run services describe rag-server-svc-plus \
|
||||||
|
--region asia-northeast1 \
|
||||||
|
--project xzerolab-480008 \
|
||||||
|
--format="value(status.url)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**可能原因**:
|
||||||
|
- PostgreSQL 服务未运行
|
||||||
|
- 密码错误
|
||||||
|
- 数据库名称错误
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**最后更新**: 2026-01-26
|
||||||
|
**负责人**: DevOps Team
|
||||||
|
**审核人**: Tech Lead
|
||||||
48
Runbook/README.md
Normal file
48
Runbook/README.md
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
# Runbook 目录
|
||||||
|
|
||||||
|
本目录包含该项目的运维手册和故障排查文档。
|
||||||
|
|
||||||
|
## 📚 文档分类
|
||||||
|
|
||||||
|
### 🔧 部署相关
|
||||||
|
- 部署流程
|
||||||
|
- 环境配置
|
||||||
|
- 依赖管理
|
||||||
|
|
||||||
|
### 🚨 故障排查
|
||||||
|
- 常见问题
|
||||||
|
- 错误诊断
|
||||||
|
- 应急处理
|
||||||
|
|
||||||
|
### 🔄 运维操作
|
||||||
|
- 日常维护
|
||||||
|
- 备份恢复
|
||||||
|
- 性能优化
|
||||||
|
|
||||||
|
### 📊 监控告警
|
||||||
|
- 监控指标
|
||||||
|
- 告警规则
|
||||||
|
- 日志分析
|
||||||
|
|
||||||
|
## 📝 文档规范
|
||||||
|
|
||||||
|
每个 Runbook 应包含：
|
||||||
|
|
||||||
|
1. **问题描述**: 清晰描述问题现象
|
||||||
|
2. **影响范围**: 说明影响的功能和用户
|
||||||
|
3. **诊断步骤**: 详细的问题定位方法
|
||||||
|
4. **修复方案**: 具体的解决步骤
|
||||||
|
5. **验证方法**: 确认问题已解决的检查清单
|
||||||
|
6. **回滚计划**: 如果修复失败的应急方案
|
||||||
|
|
||||||
|
## 🎯 命名规范
|
||||||
|
|
||||||
|
- 使用描述性的文件名
|
||||||
|
- 格式: `[类型]-[简短描述].md`
|
||||||
|
- 示例: `Deploy-Database-Migration.md`, `Fix-API-Timeout.md`
|
||||||
|
|
||||||
|
## 📅 维护说明
|
||||||
|
|
||||||
|
- 定期更新文档
|
||||||
|
- 记录最后更新时间
|
||||||
|
- 标注负责人和审核人
|
||||||
@ -148,11 +148,11 @@ function HeroSection() {
|
|||||||
<div className="flex items-center gap-4 text-sm text-text-muted">
|
<div className="flex items-center gap-4 text-sm text-text-muted">
|
||||||
<p>{t.trustedBy}</p>
|
<p>{t.trustedBy}</p>
|
||||||
<div className="flex gap-2">
|
<div className="flex gap-2">
|
||||||
<LogoPill label="Vue" />
|
<LogoPill label="Next.js" />
|
||||||
<LogoPill label="Svelte" />
|
<LogoPill label="Go" />
|
||||||
<LogoPill label="Node" />
|
<LogoPill label="Vercel" />
|
||||||
<LogoPill label="Django" />
|
<LogoPill label="Cloud Run" />
|
||||||
<LogoPill label="Laravel" />
|
<LogoPill label="PostgreSQL" />
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
@ -1077,7 +1077,7 @@ export const translations: Record<'en' | 'zh', Translation> = {
|
|||||||
tutorials: 'View Tutorials',
|
tutorials: 'View Tutorials',
|
||||||
},
|
},
|
||||||
signedIn: 'Signed in',
|
signedIn: 'Signed in',
|
||||||
trustedBy: 'Trusted by your dev team',
|
trustedBy: 'Cloud-native · Vendor-neutral · Freely portable',
|
||||||
heroCards: [
|
heroCards: [
|
||||||
{
|
{
|
||||||
title: 'Create your app',
|
title: 'Create your app',
|
||||||
@ -1784,7 +1784,7 @@ export const translations: Record<'en' | 'zh', Translation> = {
|
|||||||
tutorials: '查看教程',
|
tutorials: '查看教程',
|
||||||
},
|
},
|
||||||
signedIn: '已登录',
|
signedIn: '已登录',
|
||||||
trustedBy: '被您的开发团队信赖',
|
trustedBy: '云原生 · 去平台绑定 · 可自由迁移',
|
||||||
heroCards: [
|
heroCards: [
|
||||||
{
|
{
|
||||||
title: '创建您的应用',
|
title: '创建您的应用',
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user