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 当前目录结构

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 当前可运行能力

命令：

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 外部组件桥接

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

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. 目标技术架构

海外用户
  ↓
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