aurask/Aurask_Technical_Operations_Plan.md

# Aurask 技术与运营方案（当前实现路径版）

> 本文档基于当前仓库实现、`AGENTS.md` 约束与 `deploy/k3s/README.md` 部署规划更新。  
> 核心方向不变：面向海外用户，用 Langflow 承载模板化工作流，用 AnythingLLM 承载知识库/RAG，用 Aurask 自身网关统一做鉴权、套餐、TBU、订单、审计和运维闭环。

## 0. 当前结论

Aurask 当前已完成 **可运行 MVP 后端骨架**：

- 使用 Python 模块化单体实现首版领域闭环。
- 已具备 `Auth + API Gateway`、`Billing + Quota + TBU Ledger`、`Workflow Orchestrator`、`Knowledge Base`、`USDT-TRC20 Payment`、`Audit` 等核心边界。
- 已按产品职责划分根目录：`api`、`protal`、`manager`、`deploy`。
- 已补充 PostgreSQL、PGVector、Redis、AnythingLLM、Langflow 的桥接配置与接口契约。
- 已提供 CLI 演示与标准库 HTTP 网关。
- 已新增面向 `300` 名月度活跃用户的 `k3s` 部署规划：`deploy/k3s/README.md`。

当前阶段定位：

- **可以用于本地演示、业务流程验证、接口联调和领域模型迭代。**
- **尚不是生产部署版本。**
- 生产化需要依次补齐 PostgreSQL、队列、真实 Langflow/AnythingLLM 接入、k3s manifests、监控告警、备份恢复和支付风控。

## 1. 项目目标

Aurask 是面向海外个人开发者、学生、独立创业者和小团队的轻量级 AI 数字员工工作流平台。

目标能力：

- 用户无需自行部署 Langflow / AnythingLLM。
- 用户通过 Aurask 选择审核过的数字员工模板。
- 用户可绑定知识库 Workspace，并通过 RAG 支撑业务问答。
- Aurask 统一管理租户、套餐、TBU、订单、支付、审计和成本。
- 首期支持 USDT-TRC20 支付，后续接入 Stripe / Paddle / Lemon Squeezy 等合规渠道。

## 2. 当前代码实现

### 2.1 当前目录结构

```text
api/
  README.md               # API 与外部组件桥接说明
  requests/
    aurask-api.http       # 前端到后端请求样例
  aurask/
  __init__.py              # 包入口，导出 CLI main
  __main__.py              # python -m aurask 入口
  app.py                   # 应用装配与 demo bootstrap
  api.py                   # 标准库 HTTP 网关
  bridge_status.py         # 组件桥接状态
  cli.py                   # aurask demo / aurask serve
  repository.py            # MVP JSON 持久化
  errors.py                # 应用错误类型
  ids.py                   # ID 与时间工具
  audit.py                 # 审计事件
  auth.py                  # 租户、用户、API Key
  plans.py                 # 套餐与商品目录
  billing.py               # 订单、订阅、权益发放
  quota.py                 # TBU 额度账户、预扣、结算、账本
  payments.py              # USDT-TRC20 支付匹配
  orchestrator.py          # 模板工作流编排与 Langflow Runtime 适配
  knowledge_base.py        # AnythingLLM Workspace / 文档接入适配
  bridges/
    config.py              # PostgreSQL/PGVector/Redis/AnythingLLM/Langflow 环境配置
    postgres.py            # PostgreSQL schema contract
    pgvector.py            # PGVector tenant-filtered collection contract
    redis_bridge.py        # Redis queue/cache/idempotency key contract
    anythingllm.py         # AnythingLLM API bridge
    langflow.py            # Langflow Runtime bridge
protal/
  index.html               # 用户前端使用面板
  main.js
  styles.css
manager/
  index.html               # 管理员前端使用面板
  main.js
  styles.css
tests/
  test_mvp.py              # MVP 核心流程测试
deploy/k3s/
  README.md                # 300 MAU k3s 部署规划
```

### 2.2 当前可运行能力

命令：

```bash
uv run aurask demo --reset
uv run aurask serve --reset --host 127.0.0.1 --port 8080
python -m unittest discover -s tests -v
```

公开 API：

- `GET /health`
- `GET /plans`
- `POST /demo/bootstrap`
- `POST /tenants`

鉴权 API：

- `GET /quota`
- `GET /workflow-templates`
- `POST /workspaces`
- `POST /documents`
- `POST /orders`
- `POST /payments/match`
- `POST /workflow-runs`
- `GET /workflow-runs/{run_id}`

### 2.3 当前 MVP 简化点

| 能力 | 当前实现 | 生产目标 |
| --- | --- | --- |
| 持久化 | 本地 JSON 文件 | PostgreSQL + PGVector |
| 队列 | 同进程同步执行 | Redis / RabbitMQ / NATS 队列 |
| Langflow | 默认模拟适配层，可用 `LangflowBridge` 接真实服务 | 内部 `ClusterIP` Langflow Runtime Pool |
| AnythingLLM | 默认模拟适配层，可用 `AnythingLLMBridge` 接真实服务 | 内部 `ClusterIP` AnythingLLM API |
| 网关 | Python 标准库 HTTP Server | FastAPI / ASGI + Ingress + HPA |
| 支付 | 人工提交 tx hash 匹配 | TronGrid / Tronscan / 自建节点监听 |
| 观测 | 审计事件写入 store | Prometheus + Loki + Grafana + Alertmanager |
| 部署 | 本地运行 | k3s：`aurask-api` + `aurask-worker` |

### 2.4 根目录职责

| 根目录 | 职责 |
| --- | --- |
| `api` | 后端服务、外部组件桥接配置、前端请求契约 |
| `protal` | 用户前端使用面板。目录名按当前需求使用 `protal` 拼写 |
| `manager` | 管理员前端使用面板 |
| `deploy` | k3s 与后续部署配置 |

### 2.5 外部组件桥接

生产桥接通过环境变量启用：

```bash
AURASK_USE_EXTERNAL_BRIDGES=true
AURASK_DATABASE_URL=postgresql://aurask:secret@postgres:5432/aurask
AURASK_REDIS_URL=redis://redis:6379/0
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>
```

桥接模块：

- `api/aurask/bridges/postgres.py`：PostgreSQL schema contract。
- `api/aurask/bridges/pgvector.py`：PGVector collection 与租户过滤契约。
- `api/aurask/bridges/redis_bridge.py`：队列、缓存、幂等键、限流键约定。
- `api/aurask/bridges/anythingllm.py`：AnythingLLM Workspace / 文档入库桥接。
- `api/aurask/bridges/langflow.py`：Langflow 安全模板运行桥接。

管理员可通过鉴权接口查看桥接配置状态：

- `GET /admin/bridge-status`

## 3. 目标技术架构

```text
海外用户
  ↓
Aurask Web / 用户中心 / 支付页
  ↓
Auth + API Gateway（鉴权、限流、套餐、TBU 预扣）
  ↓
Billing & Quota Service（订单、余额、TBU、栏位、存储）
  ↓
Workflow Orchestrator（模板、任务队列、运行状态）
  ├─ Langflow Runtime Pool（模板工作流执行）
  ├─ AnythingLLM API（Workspace、文档、RAG、聊天）
  ├─ LLM Proxy（模型路由、Token 计量、成本归集）
  └─ PostgreSQL / Redis / Object Storage / Vector DB
  ↓
Observability（日志、指标、审计、告警、成本报表）
```

核心原则：

- **Aurask 网关是唯一公网入口。**
- `Langflow`、`AnythingLLM`、数据库、向量库、Redis 不直接暴露公网。
- 所有核心实体默认携带 `tenant_id`。
- 所有用户侧 Token 统一记为 `TBU`。
- 工作流执行前预扣 TBU，执行后按实际消耗结算。
- 基础用户只运行审核过的模板，不开放任意代码执行。

## 4. 多租户与安全隔离

### 4.1 领域标识

核心字段：

- `tenant_id`
- `user_id`
- `workspace_id`
- `flow_id`
- `plan_id`
- `order_id`

要求：

- 查询、写入、缓存、对象存储路径、向量检索都必须带租户维度。
- 不允许只按主键查询而不校验 `tenant_id`。
- 高付费独立空间可以独立 Namespace / Pod / 数据库凭证，但领域模型保持一致。

### 4.2 Langflow 安全边界

Langflow 只作为工作流编排/执行引擎，不作为多租户安全边界。

基础套餐：

- 只允许模板化工作流。
- 用户不进入 Langflow 全功能 UI。
- 禁止任意 Python 执行。
- 禁止任意自定义组件。
- 禁止无白名单外部网络调用。

生产建议配置：

- `LANGFLOW_AUTO_LOGIN=False`
- `LANGFLOW_FALLBACK_TO_ENV_VAR=False`
- `LANGFLOW_SECRET_KEY` 使用高强度随机值并定期轮换。
- `LANGFLOW_DATABASE_URL` 指向 PostgreSQL。
- Runtime Pod 设置 CPU、内存、pids、超时、临时目录和 egress 白名单。

### 4.3 AnythingLLM 边界

AnythingLLM 负责 Workspace、文档、RAG 和聊天历史。

要求：

- Workspace 与 Aurask `tenant_id` 绑定。
- 普通用户只能访问被显式授权的 Workspace。
- 文档必须先经过 Aurask 上传入口，再转发给 AnythingLLM。
- 上传链路预留大小、类型、病毒扫描、敏感内容检测钩子。
- 向量 metadata 必须包含 `tenant_id` 与 `workspace_id`。

## 5. 套餐、资源与 TBU

### 5.1 套餐口径

| 套餐/资源 | 价格 | 权益 | 限制 |
| --- | ---: | --- | --- |
| 免费体验 | 0 | 1 个模板工作流、1 个知识库、512MB、7 天 | 限速、低并发、不可调用高成本模型 |
| 基础套餐 | 20 USDT/月 | 3 个工作流、3 个知识库、1GB、900 TBU/月 | 仅模板/受控组件，超额需购买 TBU |
| 新增工作流栏位 | 20 USDT/个/月 | +1 工作流、+1 知识库、+1GB | 不额外赠送 TBU |
| TBU 加购 | 0.15 元/TBU 起 | 1000 TBU 送 100；2000 TBU 送 250 | 赠送额度有效期需明确 |
| 高付费独立空间 | 99 USDT/月起或定制报价 | 独立容器/命名空间、更高并发、更大存储 | 保留 egress 白名单与审计 |

### 5.2 TBU 计量流程

1. 用户发起工作流。
2. Orchestrator 按模板、输入长度、RAG TopK、预计输出长度估算 TBU。
3. Quota Service 冻结预计 TBU。
4. 余额不足则拒绝执行或提示充值/降级模型。
5. Runtime 执行工作流。
6. 执行成功后按实际 TBU 结算，释放未用额度。
7. 执行失败时：
   - 供应商未计费：全额释放。
   - 供应商已计费：按实际消耗扣减并记录失败原因。

### 5.3 当前代码对应

- 套餐定义：`api/aurask/plans.py`
- 额度账户：`api/aurask/quota.py`
- 订单与权益：`api/aurask/billing.py`
- 使用记录：`api/aurask/orchestrator.py`

## 6. 支付与订单闭环

首期使用 `USDT-TRC20`，但必须围绕“可审计订单”设计。

最低闭环：

1. 用户选择套餐或 TBU 包。
2. 系统生成订单号、金额、链、收款地址、过期时间。
3. 用户转账。
4. 系统记录 `tx_hash`、金额、确认数。
5. 金额与订单匹配。
6. 达到确认数后开通权益。
7. 异常金额、重复交易、超时到账进入人工处理队列。

当前代码：

- 订单生成：`BillingService.create_order`
- 支付匹配：`PaymentService.match_trc20_payment`
- 权益发放：`BillingService.fulfill_order`

注意：

- TRC20 手续费由 TRON Bandwidth / Energy / TRX 资源模型决定，不是 BTC 手续费。
- 生产环境必须接入链上监听与幂等校验。
- 需要保留退款、AML、税务与异常处理字段。

## 7. 数据与存储

### 7.1 MVP

当前 MVP 使用 `JsonStore`：

- 优点：无依赖、便于演示、可快速验证领域流程。
- 限制：不适合生产、无并发事务、无查询能力、无数据库级隔离。

### 7.2 生产目标

| 类型 | 推荐 |
| --- | --- |
| 主数据库 | PostgreSQL |
| 向量检索 | PGVector 起步，后续 Qdrant / Weaviate |
| 缓存与队列 | Redis 起步，后续按规模引入 RabbitMQ / NATS |
| 对象存储 | 外部 S3 兼容存储 |
| 备份 | PostgreSQL WAL 归档 + 对象存储备份 |

数据要求：

- 核心表必须包含 `tenant_id`。
- 对象路径遵循 `tenant_id/workspace_id/document_id`。
- 审计不记录完整 Prompt、完整文档正文和原始密钥。

## 8. k3s 生产部署规划

详细方案见：`deploy/k3s/README.md`。

### 8.1 300 MAU 标准

容量假设：

- 月度活跃付费用户：`300`
- 日活高峰：`40-80`
- 同时在线峰值：`15-30`
- 同时工作流执行峰值：`10-20`
- 外部模型 API，不在集群内自建 GPU 推理。

推荐拓扑：

| 角色 | 数量 | 建议配置 |
| --- | ---: | --- |
| Public LB | 1 | 云 LB 或 `HAProxy/Keepalived` |
| k3s server | 3 | `4 vCPU / 8GB RAM / 120GB SSD` |
| General worker | 2 | `8 vCPU / 16GB RAM / 200GB SSD` |
| AI/runtime worker | 2 | `8 vCPU / 16GB RAM / 250GB SSD` |

### 8.2 工作负载

| 工作负载 | 副本 | 说明 |
| --- | ---: | --- |
| `aurask-api` | 3 | 网关、鉴权、订单、额度查询 |
| `aurask-worker` | 3 | 工作流编排、异步任务、支付匹配 |
| `aurask-cron` | 1 | 周期任务、过期订单、报表 |
| `langflow-runtime` | 3 | 审核模板执行 |
| `anythingllm` | 2 | Workspace、文档、RAG |
| PostgreSQL / PGVector | 3 | CloudNativePG |
| Redis | 2-3 | 队列、缓存、限流 |

### 8.3 生产化要求

- Traefik / Ingress 只暴露 Aurask Web/API。
- cert-manager 管理 TLS。
- Longhorn 或云块存储承载 PVC。
- PostgreSQL 备份到外部 S3。
- Prometheus、Grafana、Loki、Alertmanager 提供观测。
- NetworkPolicy 默认拒绝，按服务链路放通。

## 9. 运维与可观测性

必须观测：

- API QPS、延迟、错误率。
- 工作流运行数、失败率、排队时长。
- TBU 预扣、消耗、释放、退款。
- 订单创建、支付匹配、异常订单。
- PostgreSQL 连接数、复制延迟、磁盘。
- Redis 内存、队列长度、命中率。
- Langflow / AnythingLLM 请求耗时和失败率。

告警优先级：

- `P1`：API 不可用、数据库不可写、支付匹配失败。
- `P2`：工作流失败率升高、队列堆积、文档入库堆积。
- `P3`：磁盘使用率高、备份失败、证书续期异常。

## 10. 运营方案

### 10.1 定位

面向海外小团队的低门槛 AI 数字员工平台：

- 不用自建 Langflow / AnythingLLM。
- 内置客服、知识库问答、邮件助理、表格处理、社媒内容等模板。
- 统一管理知识库、工作流、TBU 和支付。
- 默认英文 UI，后续多语言。

### 10.2 获客

优先渠道：

- GitHub 模板工作流与 SDK 示例。
- Medium / Dev.to 英文教程。
- Product Hunt / BetaList。
- Reddit / Discord / Telegram 圈层运营。
- Google Search 小词与 AI 工具导航站赞助。

冷启动预算建议：

- 内容与社群优先。
- 付费投放 `3000-8000 元/月` 起步。
- 每周复盘 CAC、激活率、付费率、退款率。

### 10.3 激活

首个 10 分钟体验路径：

1. 注册。
2. 选择模板。
3. 创建 Workspace。
4. 上传样例文档或使用示例知识库。
5. 运行一次模板工作流。
6. 看到 TBU 消耗、节省时间和下一步建议。

## 11. 财务测算口径

基准假设仍沿用原方案，但与 TBU 口径对齐：

| 项目 | 基准 |
| --- | --- |
| 付费用户 | 300 |
| 基础套餐 | 20 USDT/月 |
| 新增栏位 | 160 个/月 |
| TBU 加购 | 60 人/月，平均 800 TBU |
| 汇率 | 1 USDT ≈ 6.86 元 |
| TBU 成本 | 供应商侧 0.06 元/单位，用户侧 1 TBU = 0.8 供应商单位 |

收入：

| 收入项 | 公式 | 金额 |
| --- | ---: | ---: |
| 基础套餐 | `300 × 20 × 6.86` | 41,160 元 |
| 新增栏位 | `160 × 20 × 6.86` | 21,952 元 |
| TBU 加购 | `60 × 800 × 0.15` | 7,200 元 |
| 月营收 |  | 70,312 元 |

成本：

| 成本项 | 金额 |
| --- | ---: |
| 基础套餐 TBU 成本 | 12,960 元 |
| 加购 TBU 成本 | 2,304 元 |
| 基础设施 | 1,500-6,000 元，视 VPS/k3s/云资源而定 |
| 运营获客 | 6,000 元起 |
| 其他工具与支付预留 | 1,100 元起 |

说明：

- 年付用户不能重复计入 MRR。
- 新增栏位不赠送 TBU。
- k3s 高可用部署成本通常高于单机 VPS，财务模型要单独列“稳定性成本”。

## 12. 落地路线图

### Phase 0：已完成

- Python 模块化单体。
- CLI demo。
- HTTP API。
- TBU 预扣与结算。
- Workspace 与租户绑定。
- USDT 订单与支付匹配骨架。
- MVP 测试。
- k3s 300 MAU 部署规划。

### Phase 1：生产数据层

- 将 `JsonStore` 替换为 PostgreSQL repository。
- 引入数据库迁移。
- 增加 Redis 队列与 worker。
- 补齐幂等键与事务边界。

### Phase 2：真实服务接入

- 接真实 Langflow Runtime Pool。
- 接真实 AnythingLLM API。
- 接 LLM Proxy。
- 接 TronGrid / Tronscan 支付监听。

### Phase 3：k3s 部署

- 编写 `deploy/k3s/base` manifests。
- 拆分 `aurask-api` 与 `aurask-worker`。
- 部署 PostgreSQL、Redis、Ingress、Secret、NetworkPolicy。
- 接入 Prometheus / Loki / Grafana / Alertmanager。

### Phase 4：商业化 Beta

- 英文 UI。
- 模板库。
- 支付异常后台。
- 周报与留存邮件。
- 用户协议、退款规则、AML 记录。

## 13. 验收标准

MVP 验收：

- `python -m unittest discover -s tests -v` 通过。
- `uv run aurask demo --reset` 可创建租户、分配套餐、创建 Workspace、运行模板工作流。
- 余额不足时阻止工作流执行。
- TBU 加购支付后能发放额度。
- 文档上传能按租户与 Workspace 记录路径。

300 MAU 生产验收：

- API P95 延迟 `< 500ms`，不含外部模型调用。
- 并发工作流 `10-20` 稳定运行。
- 工作流成功率 `95%+`。
- 支付匹配成功率 `99%+`。
- PostgreSQL 备份可恢复。
- Langflow / AnythingLLM 不暴露公网。
- NetworkPolicy 默认拒绝并按链路放通。

## 14. 参考文档

- `AGENTS.md`
- `README.md`
- `deploy/k3s/README.md`
- k3s HA：<https://docs.k3s.io/datastore/ha-embedded>
- Longhorn：<https://longhorn.io/docs/latest/deploy/install/>
- cert-manager：<https://cert-manager.io/docs/installation/>
- CloudNativePG：<https://cloudnative-pg.io/documentation/current/>
- AnythingLLM System Requirements：<https://docs.anythingllm.com/installation-docker/system-requirements>
- Langflow Security：<https://docs.langflow.org/security>