aurask/deploy/k3s/README.md

# Aurask `k3s` 部署方案（300 名月度活跃用户）

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

> 当前仓库实现仍是模块化单体 MVP。  
> 在 `k3s` 上建议先拆成 **`aurask-api` + `aurask-worker`** 两类工作负载，随后再逐步拆分为独立服务。

## 1. 容量假设

由于“300 月度活跃用户”不等于“300 并发用户”，本部署按以下合理首版假设规划：

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

如果后续出现以下任一情况，应升级到下一档集群：

- 持续并发工作流 `> 20`
- 文档总量 `> 500GB`
- 高付费独立空间用户 `> 20`
- AnythingLLM 或 Langflow 需要更强隔离时改用单租户 Namespace/Pod

## 2. 目标部署拓扑

建议采用 **`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、异步任务 |

### 2.2 为什么是这个规模

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

- `3` 个 server 节点保证 `k3s` 控制面高可用
- `4` 个 worker 节点可让应用、Runtime、数据库和监控具有基础调度弹性
- 不再沿用文档里“低价单机 VPS 拼装”的方式，而是改为 **节点池 + 调度隔离**
- 仍然控制在可运维范围内，适合首版商业化

## 3. 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 存储控制平面 |

要求：

- `Langflow`、`AnythingLLM`、`PostgreSQL`、`Redis` **不暴露公网 Ingress**
- 默认 `NetworkPolicy` 为 `deny-all`，只放通必要南北向与东西向流量
- 高付费独立用户后续可按租户扩展 `aurask-tenant-<id>` 命名空间

## 4. 组件部署清单

### 4.1 边界入口层

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

公网仅开放：

- `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` | 账单修正、过期订单、周报任务 |

建议：

- `aurask-api` 开启 `HPA`，CPU `65%` 或自定义 QPS 指标触发扩容至 `5` 副本
- `aurask-worker` 依据队列长度扩容至 `6` 副本
- `PodDisruptionBudget` 至少保证 `aurask-api minAvailable=2`

### 4.3 Runtime 层

| 工作负载 | 副本数 | 建议资源 `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 层要求：

- 使用 `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 数据层

#### 推荐首版方案

| 组件 | 建议方案 | 副本/实例 | 说明 |
| --- | --- | ---: | --- |
| PostgreSQL | `CloudNativePG` + `PGVector` | 3 | 主库 + 副本 + 自动故障切换 |
| PgBouncer | Deployment | 2 | 降低应用连接风暴 |
| Redis | StatefulSet 或 Operator | 2-3 | 会话、缓存、任务队列 |
| Object Storage | **优先外部 S3 兼容存储** | 外部 | 降低集群内状态复杂度 |

原因：

- `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` |

存储建议：

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

#### Redis 资源建议

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

Redis 在 Aurask 中主要承担：

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

## 5. 存储方案

### 5.1 首版推荐

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

### 5.2 Longhorn 使用边界

`Longhorn` 更适合：

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

`Longhorn` 不应被当成性能无限的数据库盘。  
对 PostgreSQL：

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

### 5.3 建议存储类

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

## 6. 网络与安全

### 6.1 网络策略

必须启用：

- 默认拒绝所有 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/
```

## 11. 分阶段上线顺序

### Phase 1：集群底座

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

### Phase 2：数据层

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

### Phase 3：应用层

1. 部署 `aurask-api`
2. 部署 `aurask-worker`
3. 部署 `Langflow Runtime`
4. 部署 `AnythingLLM`
5. 接通内部服务发现与 NetworkPolicy

### Phase 4：生产化

1. 开启 `HPA`
2. 打通告警
3. 打通 PostgreSQL 备份
4. 打通 Longhorn 备份
5. 完成一次恢复演练
6. 完成一次工作流压测与支付链路演练

## 12. 首版压测目标

建议上线前达到以下最低标准：

| 项目 | 目标 |
| --- | --- |
| API 可用性 | `99.5%+` |
| 健康工作流成功率 | `95%+` |
| 支付匹配成功率 | `99%+` |
| 峰值并发工作流 | `10-20` |
| P95 API 延迟 | `< 500ms`（不含外部模型调用） |
| P95 工作流排队时间 | `< 10s` |
| PostgreSQL 备份恢复演练 | 每月 1 次 |

## 13. 当前实现与目标部署的差异

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

1. 当前仍是单进程模块化单体，需要拆成 `API` 与 `Worker`
2. 当前使用本地 JSON 持久化，生产需切到 `PostgreSQL`
3. 当前 Langflow / AnythingLLM 是适配层，生产需接真实服务
4. 当前未交付 Helm/Kustomize manifests，本文档先定义目标方案

## 14. 首版推荐结论

如果 Aurask 现在就要按 **300 名月度活跃付费用户** 上 `k3s`，推荐的最稳妥首版是：

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

这个方案的重点不是“极限压低成本”，而是 **先满足 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>