Update k3s deployment plan for new project structure

2026-04-19 13:38:24 +00:00 · 2026-04-19 16:34:08 +08:00 · 2026-04-19 16:34:08 +08:00 · 848bb6c08b
commit 848bb6c08b
parent 66af3b44d9
1 changed files with 532 additions and 342 deletions
--- a/deploy/k3s/README.md
+++ b/deploy/k3s/README.md
@ -1,434 +1,624 @@
-# Aurask `k3s` 部署方案（300 名月度活跃用户）
+# Aurask `k3s` 部署计划（最新目录结构版）

-本方案用于 Aurask 首版在 `k3s` 上的生产级部署规划，目标是支撑 **约 300 名月度活跃付费用户** 的稳定运行。  
-该方案遵循 `Aurask_Technical_Operations_Plan.md` 的技术边界：**Aurask 网关为唯一公网入口、Langflow 模板化运行、AnythingLLM 与租户绑定、TBU 预扣/结算、订单台账与审计可追踪**。
+本部署计划基于当前仓库结构更新：

-> 当前仓库实现仍是模块化单体 MVP。  
-> 在 `k3s` 上建议先拆成 **`aurask-api` + `aurask-worker`** 两类工作负载，随后再逐步拆分为独立服务。
+```text
+api/       # 后端服务、桥接配置、前端到后端请求契约
+protal/    # 用户前端使用面板
+manager/   # 管理员前端使用面板
+deploy/    # k3s 与后续部署配置
+```

-## 1. 容量假设
+目标是支撑 **约 300 名月度活跃付费用户**，并满足 `Aurask_Technical_Operations_Plan.md` 中的核心边界：

-由于“300 月度活跃用户”不等于“300 并发用户”，本部署按以下合理首版假设规划：
+- Aurask 网关是唯一公网业务入口。
+- `Langflow`、`AnythingLLM`、`PostgreSQL`、`PGVector`、`Redis` 不直接暴露公网。
+- 基础用户只运行审核模板，不开放任意代码执行。
+- AnythingLLM Workspace 与 Aurask `tenant_id` 绑定。
+- 工作流执行前预扣 TBU，执行后按实际消耗结算。
+- 支付、额度、审计、成本链路可追踪。
+
+## 1. 当前代码到集群工作负载映射
+
+当前仓库虽然仍是 Python 模块化单体，但已经按生产职责拆出目录和桥接层。部署时按以下方式映射：
+
+| 仓库目录/模块 | k3s 工作负载 | 说明 |
+| --- | --- | --- |
+| `api/aurask/api.py` | `aurask-api` | HTTP 网关、鉴权、订单、额度、前端请求入口 |
+| `api/aurask/cli.py` | `aurask-api` / `aurask-worker` 启动入口 | 当前用同一镜像不同命令启动 |
+| `api/aurask/orchestrator.py` | `aurask-worker` | 工作流编排、TBU 预扣/结算、调用 Langflow |
+| `api/aurask/payments.py` | `aurask-worker` / `aurask-cron` | 支付匹配、后续链上监听 |
+| `api/aurask/bridges/postgres.py` | `aurask-api` / `aurask-worker` | PostgreSQL schema contract |
+| `api/aurask/bridges/pgvector.py` | `aurask-worker` | 向量检索契约，强制租户过滤 |
+| `api/aurask/bridges/redis_bridge.py` | `aurask-api` / `aurask-worker` | 队列、缓存、幂等、限流 key 规则 |
+| `api/aurask/bridges/anythingllm.py` | `aurask-worker` | AnythingLLM Workspace / 文档入库桥接 |
+| `api/aurask/bridges/langflow.py` | `aurask-worker` | Langflow 模板运行桥接 |
+| `protal/` | `aurask-protal` | 用户前端静态站点 |
+| `manager/` | `aurask-manager` | 管理员前端静态站点 |
+| `deploy/k3s/` | GitOps / Kustomize / Helm | 部署配置根目录 |
+
+## 2. 容量假设
+
+300 MAU 首版不是 300 并发。按以下容量规划：

 - 月度活跃付费用户：`300`
 - 日活高峰：`40-80`
 - 同时在线用户峰值：`15-30`
 - 同时工作流执行峰值：`10-20`
- 基础套餐为主，绝大部分用户运行 **模板化 Langflow 工作流**
- 外部大模型走 API / Proxy 路由，**不在集群内自建 GPU 推理**
- AnythingLLM 文档总量控制在 `500GB` 以内
- 向量层优先采用 `PostgreSQL + PGVector`
+- 文档总量：`<= 500GB`
+- 向量层：首版 `PostgreSQL + PGVector`
+- 模型推理：外部模型 API / LLM Proxy，不在集群内自建 GPU 推理
+- Runtime：基础用户共享 Runtime Pool，高付费用户后续独立 Namespace

-如果后续出现以下任一情况，应升级到下一档集群：
+触发扩容条件：

 - 持续并发工作流 `> 20`
 - 文档总量 `> 500GB`
 - 高付费独立空间用户 `> 20`
- AnythingLLM 或 Langflow 需要更强隔离时改用单租户 Namespace/Pod
+- 工作流排队 P95 `> 10s`
+- PostgreSQL 连接数、WAL、磁盘或 CPU 持续接近上限

-## 2. 目标部署拓扑
+## 3. 集群拓扑

-建议采用 **`3` 台 control-plane + `4` 台 worker + `1` 个公网负载均衡入口** 的最小高可用拓扑。
-
-### 2.1 节点规划
+推荐首版生产拓扑：

 | 角色 | 数量 | 建议配置 | 用途 |
 | --- | ---: | --- | --- |
-| Public LB | 1 | 云负载均衡或双机 `HAProxy/Keepalived` | 统一暴露 `80/443` |
-| `k3s` server | 3 | `4 vCPU / 8GB RAM / 120GB SSD` | API Server、Scheduler、Controller、embedded etcd |
-| General worker | 2 | `8 vCPU / 16GB RAM / 200GB SSD` | `aurask-api`、`aurask-worker`、Traefik、observability |
-| AI/runtime worker | 2 | `8 vCPU / 16GB RAM / 250GB SSD` | Langflow Runtime、AnythingLLM、异步任务 |
+| Public LB | 1 | 云负载均衡或 `HAProxy/Keepalived` | 统一暴露 `80/443` |
+| `k3s` server | 3 | `4 vCPU / 8GB RAM / 120GB SSD` | 控制面 + embedded etcd |
+| General worker | 2 | `8 vCPU / 16GB RAM / 200GB SSD` | `aurask-api`、前端、Ingress、观测 |
+| Runtime worker | 2 | `8 vCPU / 16GB RAM / 250GB SSD` | `aurask-worker`、Langflow、AnythingLLM |
+| Data worker | 可选 1-2 | `8 vCPU / 16GB RAM / 300GB+ SSD/NVMe` | PostgreSQL、Redis、存储密集型组件 |

-### 2.2 为什么是这个规模
+如果预算有限，可先用 `3 server + 4 worker`，将 Data worker 合并到 worker 池；但 PostgreSQL 节点必须通过反亲和规则打散。

-这个规格对应的是 **“300 MAU、10-20 并发工作流、外部模型 API”** 的首个生产档：
+## 4. Namespace 规划

- `3` 个 server 节点保证 `k3s` 控制面高可用
- `4` 个 worker 节点可让应用、Runtime、数据库和监控具有基础调度弹性
- 不再沿用文档里“低价单机 VPS 拼装”的方式，而是改为 **节点池 + 调度隔离**
- 仍然控制在可运维范围内，适合首版商业化
-
-## 3. Namespace 设计
-
-建议至少划分以下命名空间：
-
-| Namespace | 作用 |
+| Namespace | 组件 |
 | --- | --- |
-| `ingress-system` | Traefik / LoadBalancer 相关资源 |
-| `cert-manager` | TLS 证书管理 |
-| `aurask-system` | Aurask API、Worker、CronJob、Secrets |
-| `aurask-runtime` | Langflow Runtime、AnythingLLM |
-| `aurask-data` | PostgreSQL、Redis、内部状态性服务 |
-| `observability` | Prometheus、Loki、Grafana、Alertmanager |
-| `longhorn-system` | Longhorn 存储控制平面 |
+| `ingress-system` | Traefik / Nginx Ingress、External DNS |
+| `cert-manager` | TLS 证书 |
+| `aurask-api` | `aurask-api`、API Secret、API ServiceAccount |
+| `aurask-web` | `aurask-protal`、`aurask-manager` 静态前端 |
+| `aurask-runtime` | `aurask-worker`、`langflow-runtime`、`anythingllm` |
+| `aurask-data` | PostgreSQL、PGVector、PgBouncer、Redis |
+| `observability` | Prometheus、Grafana、Loki、Alertmanager |
+| `longhorn-system` | Longhorn |

 要求：

- `Langflow`、`AnythingLLM`、`PostgreSQL`、`Redis` **不暴露公网 Ingress**
- 默认 `NetworkPolicy` 为 `deny-all`，只放通必要南北向与东西向流量
- 高付费独立用户后续可按租户扩展 `aurask-tenant-<id>` 命名空间
+- 默认 `NetworkPolicy` 为 `deny-all`。
+- 只允许 `aurask-api` 接收公网 Ingress 流量。
+- `aurask-protal`、`aurask-manager` 可以暴露公网，但它们只访问 `aurask-api`。
+- `Langflow`、`AnythingLLM`、`PostgreSQL`、`Redis` 仅 `ClusterIP`。

-## 4. 组件部署清单
+## 5. 应用工作负载

-### 4.1 边界入口层
+### 5.1 `aurask-api`

-| 组件 | 副本数 | 部署位置 | 说明 |
-| --- | ---: | --- | --- |
-| Traefik | 2 | `ingress-system` | 统一入口，终止 TLS |
-| cert-manager | 2 | `cert-manager` | 自动签发 TLS 证书 |
-| External DNS | 1 | `ingress-system` | 可选，自动写 DNS |
+来源：

-公网仅开放：
+- `api/aurask/api.py`
+- `api/aurask/app.py`
+- `api/aurask/auth.py`
+- `api/aurask/billing.py`
+- `api/aurask/quota.py`

- `80/tcp`
- `443/tcp`
+职责：

-Aurask 对外只暴露：
-
- `aurask-web`
- `aurask-api`
-
-**不要**暴露：
-
- Langflow UI
- AnythingLLM 管理后台
- PostgreSQL
- Redis
- 内部 worker
-
-### 4.2 Aurask 应用层
-
-首版建议从同一个镜像拆出两个工作负载：
-
-| 工作负载 | 副本数 | 建议资源 `requests` | 建议资源 `limits` | 说明 |
-| --- | ---: | --- | --- | --- |
-| `aurask-api` | 3 | `500m CPU / 1Gi RAM` | `1 CPU / 2Gi RAM` | 网关、鉴权、订单、额度查询 |
-| `aurask-worker` | 3 | `1 CPU / 2Gi RAM` | `2 CPU / 4Gi RAM` | 工作流编排、异步执行、支付匹配、后台任务 |
-| `aurask-cron` | 1 | `250m CPU / 512Mi RAM` | `500m CPU / 1Gi RAM` | 账单修正、过期订单、周报任务 |
+- HTTP 网关。
+- 鉴权。
+- 租户上下文注入。
+- 套餐、订单、额度查询。
+- 前端请求入口。
+- 管理端桥接状态接口：`GET /admin/bridge-status`。

 建议：

- `aurask-api` 开启 `HPA`，CPU `65%` 或自定义 QPS 指标触发扩容至 `5` 副本
- `aurask-worker` 依据队列长度扩容至 `6` 副本
- `PodDisruptionBudget` 至少保证 `aurask-api minAvailable=2`
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `3` |
+| requests | `500m CPU / 1Gi RAM` |
+| limits | `1 CPU / 2Gi RAM` |
+| HPA | CPU 65% 或 QPS 指标，扩到 `5` |
+| PDB | `minAvailable=2` |

-### 4.3 Runtime 层
+### 5.2 `aurask-worker`

-| 工作负载 | 副本数 | 建议资源 `requests` | 建议资源 `limits` | 说明 |
-| --- | ---: | --- | --- | --- |
-| `langflow-runtime` | 3 | `1500m CPU / 3Gi RAM` | `3 CPU / 6Gi RAM` | 仅运行审核模板，不开放任意代码执行 |
-| `anythingllm` | 2 | `1 CPU / 2Gi RAM` | `2 CPU / 4Gi RAM` | Workspace、文档、RAG、聊天记录 |
+来源：

-Runtime 层要求：
+- `api/aurask/orchestrator.py`
+- `api/aurask/knowledge_base.py`
+- `api/aurask/payments.py`
+- `api/aurask/bridges/*`

- 使用 `nodeSelector` 或 `taints/tolerations` 调度到 `AI/runtime worker`
- `Langflow` 开启安全配置：
-  - `LANGFLOW_AUTO_LOGIN=False`
-  - `LANGFLOW_FALLBACK_TO_ENV_VAR=False`
-  - `LANGFLOW_DATABASE_URL` 指向集群内 PostgreSQL
- `AnythingLLM` 只允许通过 Aurask 网关与后台服务访问
- 两者都只通过 `ClusterIP` 暴露
+职责：

-### 4.4 数据层
+- 工作流编排。
+- TBU 预扣与结算。
+- 调用 Langflow Runtime。
+- 调用 AnythingLLM。
+- 处理文档入库。
+- 后续消费 Redis 队列。

-#### 推荐首版方案
+建议：

-| 组件 | 建议方案 | 副本/实例 | 说明 |
-| --- | --- | ---: | --- |
-| PostgreSQL | `CloudNativePG` + `PGVector` | 3 | 主库 + 副本 + 自动故障切换 |
-| PgBouncer | Deployment | 2 | 降低应用连接风暴 |
-| Redis | StatefulSet 或 Operator | 2-3 | 会话、缓存、任务队列 |
-| Object Storage | **优先外部 S3 兼容存储** | 外部 | 降低集群内状态复杂度 |
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `3` |
+| requests | `1 CPU / 2Gi RAM` |
+| limits | `2 CPU / 4Gi RAM` |
+| HPA/KEDA | 按 Redis 队列长度扩到 `6` |
+| 调度 | 优先 Runtime worker |

-原因：
+### 5.3 `aurask-cron`

- `PGVector` 可同时承载业务数据库与向量检索，适合 Aurask 首版
- `CloudNativePG` 比自建主从脚本更适合作为 `k3s` 首版生产标准
- 文档对象、备份对象尽量放到外部对象存储，避免首版把 `MinIO`、数据库、向量库、应用全部堆在一个小集群里
+职责：

-#### PostgreSQL 资源建议
+- 过期订单处理。
+- 支付异常扫描。
+- 周报/月报。
+- 备份检查。
+- 成本报表归集。

-| 组件 | 副本数 | `requests` | `limits` |
-| --- | ---: | --- | --- |
-| `cnpg-cluster` instance | 3 | `2 CPU / 4Gi RAM` | `4 CPU / 8Gi RAM` |
-| `pgbouncer` | 2 | `500m CPU / 512Mi RAM` | `1 CPU / 1Gi RAM` |
+建议：

-存储建议：
+| 项目 | 值 |
+| --- | --- |
+| 类型 | `CronJob` |
+| requests | `250m CPU / 512Mi RAM` |
+| limits | `500m CPU / 1Gi RAM` |

- 数据卷：每实例 `200GB` 起
- 存储类型：优先云块存储 / CSI Block / 本地 NVMe
- 如果必须首版全部自建，可使用 `Longhorn`，但数据库卷要使用更快磁盘池
+### 5.4 `aurask-protal`

-#### Redis 资源建议
+来源：`protal/`

-| 组件 | 副本数 | `requests` | `limits` |
-| --- | ---: | --- | --- |
-| `redis` | 2 | `500m CPU / 1Gi RAM` | `1 CPU / 2Gi RAM` |
+职责：

-Redis 在 Aurask 中主要承担：
+- 用户登录后的使用面板。
+- 调用 Aurask API。
+- 创建 Workspace、运行模板、查看额度。

- 会话
- 幂等键
- 工作流队列
- 限流与短期缓存
+建议：

-## 5. 存储方案
+| 项目 | 值 |
+| --- | --- |
+| 类型 | 静态站点 Deployment |
+| 副本 | `2` |
+| requests | `50m CPU / 64Mi RAM` |
+| limits | `200m CPU / 256Mi RAM` |
+| Ingress host | `app.aurask.example.com` |

-### 5.1 首版推荐
+### 5.5 `aurask-manager`

- `Longhorn`：为集群内 PVC 提供高可用块存储
- 外部 S3 兼容对象存储：保存文档对象、PostgreSQL 备份、审计归档、Longhorn 备份
+来源：`manager/`

-### 5.2 Longhorn 使用边界
+职责：

-`Longhorn` 更适合：
+- 管理员使用面板。
+- 查看桥接状态。
+- 后续扩展租户、订单、异常支付、成本、审计。

- 应用 PVC
- AnythingLLM 一般性文档缓存
- Redis/监控等非极端 IOPS 场景
+建议：

-`Longhorn` 不应被当成性能无限的数据库盘。  
-对 PostgreSQL：
+| 项目 | 值 |
+| --- | --- |
+| 类型 | 静态站点 Deployment |
+| 副本 | `2` |
+| requests | `50m CPU / 64Mi RAM` |
+| limits | `200m CPU / 256Mi RAM` |
+| Ingress host | `manager.aurask.example.com` |
+| 额外保护 | IP allowlist / SSO / BasicAuth / 二次认证 |

- 最优是云块存储或本地 NVMe + 复制/备份
- 次优才是 `Longhorn` 高副本卷
+## 6. Runtime 组件

-### 5.3 建议存储类
+### 6.1 Langflow Runtime

-| StorageClass | 用途 | 副本数 |
-| --- | --- | ---: |
-| `longhorn-general` | 应用与一般 PVC | 2 |
-| `longhorn-critical` | AnythingLLM、审计、重要状态 | 3 |
-| `cnpg-fast` | PostgreSQL | 3 或使用外部 CSI |
+部署名：`langflow-runtime`

-## 6. 网络与安全
+用途：

-### 6.1 网络策略
+- 仅执行 Aurask 审核过的模板工作流。
+- 不向普通用户暴露 Langflow UI。
+- 被 `aurask-worker` 通过内部 Service 调用。
+
+建议：
+
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `3` |
+| requests | `1500m CPU / 3Gi RAM` |
+| limits | `3 CPU / 6Gi RAM` |
+| Service | `ClusterIP` |
+| 调度 | Runtime worker |
+
+关键环境变量：
+
+```text
+LANGFLOW_AUTO_LOGIN=False
+LANGFLOW_FALLBACK_TO_ENV_VAR=False
+LANGFLOW_DATABASE_URL=postgresql://...
+LANGFLOW_SECRET_KEY=<secret>
+```
+
+Aurask 侧桥接：
+
+```text
+AURASK_LANGFLOW_BASE_URL=http://langflow-runtime.aurask-runtime.svc.cluster.local:7860
+AURASK_LANGFLOW_API_KEY=<secret>
+```
+
+### 6.2 AnythingLLM
+
+部署名：`anythingllm`
+
+用途：
+
+- Workspace。
+- 文档入库。
+- RAG。
+- 聊天历史。
+
+建议：
+
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `2` |
+| requests | `1 CPU / 2Gi RAM` |
+| limits | `2 CPU / 4Gi RAM` |
+| Service | `ClusterIP` |
+| 调度 | Runtime worker |
+
+Aurask 侧桥接：
+
+```text
+AURASK_ANYTHINGLLM_BASE_URL=http://anythingllm.aurask-runtime.svc.cluster.local:3001
+AURASK_ANYTHINGLLM_API_KEY=<secret>
+```
+
+要求：
+
+- 管理员账号仅由 Aurask 后台持有。
+- 普通用户不进入 AnythingLLM 管理后台。
+- Workspace 必须通过 Aurask 创建并绑定 `tenant_id`。
+
+## 7. 数据组件
+
+### 7.1 PostgreSQL + PGVector
+
+推荐：`CloudNativePG + PGVector`
+
+用途：
+
+- 租户、用户、订单、额度、审计。
+- 向量检索起步方案。
+
+建议：
+
+| 项目 | 值 |
+| --- | --- |
+| 实例数 | `3` |
+| requests | `2 CPU / 4Gi RAM` |
+| limits | `4 CPU / 8Gi RAM` |
+| PVC | 每实例 `200GB` 起 |
+| 备份 | WAL 归档到 S3 |
+
+Aurask schema 契约来源：
+
+- `api/aurask/bridges/postgres.py`
+- `api/aurask/bridges/pgvector.py`

 必须启用：

- 默认拒绝所有 Pod 间访问
- `aurask-api -> aurask-worker`
- `aurask-api / aurask-worker -> PostgreSQL`
- `aurask-api / aurask-worker -> Redis`
- `aurask-worker -> Langflow`
- `aurask-worker -> AnythingLLM`
- `Langflow / AnythingLLM -> 外部模型代理或白名单域名`
-
-### 6.2 入口安全
-
- 强制 HTTPS
- 开启 WAF/基础限流
- 对 `/payments/*`、`/auth/*`、`/workflow-runs` 增加速率限制
- 后台入口强制二次认证
-
-### 6.3 Secret 管理
-
-建议使用以下任一方案：
-
- `External Secrets Operator` + 外部密钥管理
- `SOPS` + `age`
-
-不要把以下信息明文提交到 Git：
-
- `LANGFLOW_SECRET_KEY`
- `DATABASE_URL`
- `TRC20` 收款钱包配置
- 第三方 LLM API Key
- SMTP / Webhook 签名密钥
-
-## 7. 可观测性
-
-建议部署：
-
-| 组件 | 作用 |
-| --- | --- |
-| Prometheus | 指标采集 |
-| Grafana | 可视化 |
-| Loki | 日志检索 |
-| Alertmanager | 告警 |
-| kube-state-metrics | 集群对象指标 |
-| node-exporter | 节点指标 |
-
-至少监控以下指标：
-
- `aurask-api` 请求量、延迟、错误率
- `workflow_runs_total`
- `workflow_run_failed_total`
- `tbu_reserved_total`
- `tbu_consumed_total`
- `queue_depth`
- `langflow_runtime_seconds`
- `anythingllm_document_ingest_seconds`
- PostgreSQL CPU、连接数、WAL、复制延迟
- Redis 内存、延迟、命中率
-
-告警优先级：
-
- `P1`：API 全站不可用、数据库主库不可写、支付匹配故障
- `P2`：工作流失败率升高、AnythingLLM 入库堆积、队列堆积
- `P3`：磁盘使用率、备份失败、证书续期异常
-
-## 8. 备份与容灾
-
-### 8.1 PostgreSQL
-
- 使用 `CloudNativePG` 做持续归档与定时备份
- 备份目标：外部 S3 兼容对象存储
- 目标：
-  - `RPO <= 15 分钟`
-  - `RTO <= 2 小时`
-
-### 8.2 Longhorn
-
- 每日快照
- 每周备份到对象存储
- 每月恢复演练一次
-
-### 8.3 AnythingLLM 与 Aurask 审计数据
-
- 文档对象外部化存储
- 审计日志每日归档
- 支付订单与链上交易匹配记录保留至少 `180` 天
-
-## 9. 推荐调度策略
-
-### 9.1 节点标签
-
-建议给节点加标签：
-
- `node-role.kubernetes.io/runtime=true`
- `node-role.kubernetes.io/general=true`
- `node-role.kubernetes.io/data=true`
-
-### 9.2 调度建议
-
- `aurask-api`：调度到 `general`
- `aurask-worker`：优先 `general`，可溢出到 `runtime`
- `langflow-runtime`：只调度到 `runtime`
- `anythingllm`：优先 `runtime`
- PostgreSQL / Redis：优先 `data` 或资源更稳定的 worker
-
-### 9.3 高可用约束
-
- `topologySpreadConstraints`
- `podAntiAffinity`
- `PodDisruptionBudget`
-
-避免：
-
- 同一应用所有副本落在同一节点
- PostgreSQL 三个实例共用同一宿主机
- Langflow 与数据库争抢同一节点全部资源
-
-## 10. 推荐发布方式
-
-建议使用：
-
- `Helm` 管理第三方组件
- `Kustomize` 管理 Aurask 自研服务
- `GitOps` 管理环境变更
-
-建议目录：
-
-```text
-deploy/
-  k3s/
-    README.md
-    base/
-      namespace.yaml
-      network-policies.yaml
-      aurask-api.yaml
-      aurask-worker.yaml
-      ingress.yaml
-    overlays/
-      staging/
-      production/
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
 ```

-## 11. 分阶段上线顺序
+### 7.2 PgBouncer
+
+用途：
+
+- 降低 API / Worker 连接风暴。
+
+建议：
+
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `2` |
+| requests | `500m CPU / 512Mi RAM` |
+| limits | `1 CPU / 1Gi RAM` |
+
+### 7.3 Redis
+
+用途：
+
+- 工作流队列。
+- 幂等键。
+- 限流。
+- 短期缓存。
+
+建议：
+
+| 项目 | 值 |
+| --- | --- |
+| 副本 | `2-3` |
+| requests | `500m CPU / 1Gi RAM` |
+| limits | `1 CPU / 2Gi RAM` |
+
+Aurask key 契约来源：
+
+- `api/aurask/bridges/redis_bridge.py`
+
+## 8. 镜像构建计划
+
+当前仓库建议构建三个镜像：
+
+| 镜像 | 来源目录 | 用途 |
+| --- | --- | --- |
+| `aurask-api` | `api/` | 后端 API 与 worker 运行时 |
+| `aurask-protal` | `protal/` | 用户前端静态站点 |
+| `aurask-manager` | `manager/` | 管理员前端静态站点 |
+
+首版可先使用同一个 Python 镜像启动 `aurask-api` 与 `aurask-worker`：
+
+```text
+aurask-api:     python -m aurask serve --host 0.0.0.0 --port 8080
+aurask-worker:  python -m aurask worker   # 后续补真实 worker 命令
+```
+
+在真实 worker 命令完成前，`aurask-worker` 可先部署为保留工作负载或运行后台 cron/队列消费者占位。
+
+## 9. 环境变量
+
+`aurask-api` 与 `aurask-worker` 共享：
+
+```text
+AURASK_USE_EXTERNAL_BRIDGES=true
+AURASK_DATABASE_URL=postgresql://aurask:<password>@pgbouncer.aurask-data.svc.cluster.local:5432/aurask
+AURASK_POSTGRES_MIN_CONNECTIONS=1
+AURASK_POSTGRES_MAX_CONNECTIONS=10
+AURASK_PGVECTOR_TABLE=aurask_vectors
+AURASK_PGVECTOR_DIMENSION=1536
+AURASK_REDIS_URL=redis://redis.aurask-data.svc.cluster.local:6379/0
+AURASK_REDIS_WORKFLOW_QUEUE=aurask:workflow-runs
+AURASK_ANYTHINGLLM_BASE_URL=http://anythingllm.aurask-runtime.svc.cluster.local:3001
+AURASK_ANYTHINGLLM_API_KEY=<secret>
+AURASK_LANGFLOW_BASE_URL=http://langflow-runtime.aurask-runtime.svc.cluster.local:7860
+AURASK_LANGFLOW_API_KEY=<secret>
+```
+
+Secret 管理：
+
+- 推荐 `External Secrets Operator`。
+- 或使用 `SOPS + age` 管理 GitOps secret。
+- 禁止将真实 API Key、数据库密码、钱包配置提交到 Git。
+
+## 10. Ingress 规划
+
+建议域名：
+
+| Host | Service | 说明 |
+| --- | --- | --- |
+| `api.aurask.example.com` | `aurask-api` | API 网关 |
+| `app.aurask.example.com` | `aurask-protal` | 用户面板 |
+| `manager.aurask.example.com` | `aurask-manager` | 管理员面板 |
+
+不创建公网 Ingress：
+
+- `langflow-runtime`
+- `anythingllm`
+- `postgres`
+- `pgbouncer`
+- `redis`
+
+管理员面板额外要求：
+
+- IP allowlist。
+- SSO / BasicAuth / 二次认证。
+- 操作审计。
+
+## 11. NetworkPolicy 规划
+
+默认拒绝所有东西向访问，然后按链路放通：
+
+| From | To | Purpose |
+| --- | --- | --- |
+| Ingress | `aurask-api` | API 流量 |
+| Ingress | `aurask-protal` | 用户面板 |
+| Ingress | `aurask-manager` | 管理面板 |
+| `aurask-api` | PgBouncer | 业务读写 |
+| `aurask-worker` | PgBouncer | 业务读写 |
+| `aurask-api` | Redis | 限流、缓存 |
+| `aurask-worker` | Redis | 队列、幂等 |
+| `aurask-worker` | Langflow | 模板执行 |
+| `aurask-worker` | AnythingLLM | Workspace / 文档 / RAG |
+| Langflow | 外部 LLM Proxy | 模型调用 |
+| AnythingLLM | 外部 LLM Proxy / Object Storage | RAG 与文档处理 |
+
+禁止：
+
+- 用户请求直接访问 Langflow / AnythingLLM。
+- 前端直接访问 PostgreSQL / Redis。
+- Runtime 访问内网管理网段、云元数据地址。
+
+## 12. 存储与备份
+
+### 12.1 PVC
+
+| 组件 | 存储 |
+| --- | --- |
+| PostgreSQL | `cnpg-fast`，优先云块存储 / NVMe |
+| Redis | `longhorn-general` 或云块存储 |
+| AnythingLLM | `longhorn-critical` 或外部对象存储缓存 |
+| Observability | `longhorn-general` |
+
+### 12.2 对象存储
+
+优先外部 S3 兼容存储，用于：
+
+- 用户文档对象。
+- PostgreSQL 备份。
+- Longhorn 备份。
+- 审计归档。
+
+### 12.3 备份目标
+
+- PostgreSQL：`RPO <= 15 分钟`，`RTO <= 2 小时`。
+- Longhorn：每日快照，每周备份。
+- 支付订单与链上交易匹配记录：至少保留 `180` 天。
+- 每月至少做一次恢复演练。
+
+## 13. 可观测性
+
+组件：
+
+- Prometheus
+- Grafana
+- Loki
+- Alertmanager
+- kube-state-metrics
+- node-exporter
+
+必须监控：
+
+- `aurask-api` QPS、P95、错误率。
+- `aurask-worker` 队列深度、执行时长、失败率。
+- `tbu_reserved_total`、`tbu_consumed_total`、`tbu_released_total`。
+- 订单创建、支付匹配、异常订单数量。
+- Langflow 执行耗时与错误率。
+- AnythingLLM 文档入库耗时与失败率。
+- PostgreSQL 连接数、WAL、复制延迟、磁盘。
+- Redis 内存、队列长度、延迟。
+
+## 14. 推荐部署配置目录
+
+后续 manifests 建议落入：
+
+```text
+deploy/k3s/
+  README.md
+  base/
+    namespaces.yaml
+    ingress.yaml
+    network-policies.yaml
+    secrets.example.yaml
+    aurask-api.yaml
+    aurask-worker.yaml
+    aurask-protal.yaml
+    aurask-manager.yaml
+    langflow-runtime.yaml
+    anythingllm.yaml
+    postgres-cnpg.yaml
+    redis.yaml
+    observability.yaml
+  overlays/
+    staging/
+      kustomization.yaml
+    production/
+      kustomization.yaml
+```
+
+Helm 管理：
+
+- `cert-manager`
+- `longhorn`
+- `cloudnative-pg`
+- `prometheus-stack`
+- `loki`
+- `redis` operator 或 chart
+
+Kustomize 管理：
+
+- Aurask 自研服务。
+- Ingress。
+- NetworkPolicy。
+- 环境差异。
+
+## 15. 上线步骤

 ### Phase 1：集群底座

-1. 创建 `3 server + 4 worker` `k3s` 集群
-2. 配置公网 LB / MetalLB / DNS
-3. 安装 `cert-manager`
-4. 安装 `Longhorn`
-5. 安装 observability 基础栈
+1. 创建 `3 server + 4 worker` k3s 集群。
+2. 配置公网 LB 与 DNS。
+3. 安装 `cert-manager`。
+4. 安装 `Longhorn` 或云 CSI。
+5. 安装 observability 基础栈。

 ### Phase 2：数据层

-1. 部署 `CloudNativePG`
-2. 初始化 `PostgreSQL + PGVector`
-3. 部署 `PgBouncer`
-4. 部署 `Redis`
-5. 配置对象存储与备份桶
+1. 安装 `CloudNativePG`。
+2. 初始化 PostgreSQL 与 PGVector。
+3. 部署 PgBouncer。
+4. 部署 Redis。
+5. 配置对象存储与备份桶。

-### Phase 3：应用层
+### Phase 3：Aurask 应用层

-1. 部署 `aurask-api`
-2. 部署 `aurask-worker`
-3. 部署 `Langflow Runtime`
-4. 部署 `AnythingLLM`
-5. 接通内部服务发现与 NetworkPolicy
+1. 构建并推送 `aurask-api` 镜像。
+2. 构建并推送 `aurask-protal` 镜像。
+3. 构建并推送 `aurask-manager` 镜像。
+4. 部署 `aurask-api`。
+5. 部署 `aurask-worker`。
+6. 部署 `aurask-protal` 与 `aurask-manager`。
+7. 配置 Ingress、TLS、NetworkPolicy。

-### Phase 4：生产化
+### Phase 4：Runtime 层

-1. 开启 `HPA`
-2. 打通告警
-3. 打通 PostgreSQL 备份
-4. 打通 Longhorn 备份
-5. 完成一次恢复演练
-6. 完成一次工作流压测与支付链路演练
+1. 部署 Langflow Runtime。
+2. 部署 AnythingLLM。
+3. 配置 `AURASK_LANGFLOW_*` 与 `AURASK_ANYTHINGLLM_*` secret。
+4. 使用 `GET /admin/bridge-status` 验证桥接配置。
+5. 跑通模板工作流与文档入库。

-## 12. 首版压测目标
+### Phase 5：生产化验收

-建议上线前达到以下最低标准：
+1. 开启 HPA / KEDA。
+2. 跑并发工作流压测。
+3. 演练支付匹配。
+4. 演练 PostgreSQL 备份恢复。
+5. 演练节点故障与 Pod 重调度。
+6. 检查 Langflow / AnythingLLM 未暴露公网。
+
+## 16. 验收标准

 | 项目 | 目标 |
 | --- | --- |
-| API 可用性 | `99.5%+` |
-| 健康工作流成功率 | `95%+` |
-| 支付匹配成功率 | `99%+` |
+| API P95 | `< 500ms`，不含外部模型调用 |
 | 峰值并发工作流 | `10-20` |
-| P95 API 延迟 | `< 500ms`（不含外部模型调用） |
-| P95 工作流排队时间 | `< 10s` |
-| PostgreSQL 备份恢复演练 | 每月 1 次 |
+| 工作流成功率 | `95%+` |
+| 支付匹配成功率 | `99%+` |
+| 工作流排队 P95 | `< 10s` |
+| PostgreSQL RPO | `<= 15 分钟` |
+| PostgreSQL RTO | `<= 2 小时` |
+| 月可用性 | `99%+` |
+| 外部暴露面 | 仅 API、用户面板、管理面板 |

-## 13. 当前实现与目标部署的差异
+## 17. 当前代码差距

-当前仓库已经具备首版领域骨架，但与 `k3s` 生产部署之间还存在以下差异：
+当前已经具备：

-1. 当前仍是单进程模块化单体，需要拆成 `API` 与 `Worker`
-2. 当前使用本地 JSON 持久化，生产需切到 `PostgreSQL`
-3. 当前 Langflow / AnythingLLM 是适配层，生产需接真实服务
-4. 当前未交付 Helm/Kustomize manifests，本文档先定义目标方案
+- 根目录划分：`api`、`protal`、`manager`、`deploy`。
+- PostgreSQL / PGVector / Redis / AnythingLLM / Langflow 桥接契约。
+- `/admin/bridge-status` 桥接状态接口。
+- 静态用户面板和管理面板。
+- 请求样例：`api/requests/aurask-api.http`。

-## 14. 首版推荐结论
+仍需补齐：

-如果 Aurask 现在就要按 **300 名月度活跃付费用户** 上 `k3s`，推荐的最稳妥首版是：
+- `deploy/k3s/base` manifests。
+- 真实 PostgreSQL repository。
+- Redis 队列消费者。
+- `aurask-worker` 独立启动命令。
+- 真实 Langflow / AnythingLLM API 适配细节校验。
+- 前端构建流程与容器镜像。
+- Secret / NetworkPolicy / HPA / KEDA manifests。

- `3` 台 `k3s server`
- `4` 台 worker
- `Traefik + cert-manager`
- `CloudNativePG + PGVector`
- `Redis`
- `Longhorn`
- `Prometheus + Grafana + Loki + Alertmanager`
- Aurask 自身先拆成 `aurask-api` 与 `aurask-worker`
- Langflow / AnythingLLM 作为内部 `ClusterIP` 服务接入
+## 18. 官方参考

-这个方案的重点不是“极限压低成本”，而是 **先满足 300 MAU 阶段的稳定性、隔离、审计、扩容和恢复能力**。
-
-## 15. 官方参考
-
-以下官方文档可作为落地实施时的基线依据：
-
- `k3s` Cluster Datastore：<https://docs.k3s.io/datastore>
- `k3s` High Availability Embedded etcd：<https://docs.k3s.io/datastore/ha-embedded>
- `cert-manager` Installation：<https://cert-manager.io/docs/installation/>
- `Longhorn` Installation / Requirements：<https://longhorn.io/docs/latest/deploy/install/>
- `CloudNativePG` Documentation：<https://cloudnative-pg.io/documentation/current/>
- `CloudNativePG` Backup：<https://cloudnative-pg.io/documentation/current/backup/>
- `AnythingLLM` Self-hosted System Requirements：<https://docs.anythingllm.com/installation-docker/system-requirements>
- `Langflow` Security：<https://docs.langflow.org/security>
+- k3s HA embedded etcd：<https://docs.k3s.io/datastore/ha-embedded>
+- cert-manager Installation：<https://cert-manager.io/docs/installation/>
+- Longhorn Installation：<https://longhorn.io/docs/latest/deploy/install/>
+- CloudNativePG Documentation：<https://cloudnative-pg.io/documentation/current/>
+- CloudNativePG Backup：<https://cloudnative-pg.io/documentation/current/backup/>
+- AnythingLLM System Requirements：<https://docs.anythingllm.com/installation-docker/system-requirements>
+- Langflow Security：<https://docs.langflow.org/security>