devcloud-admin/aurask
1
0
Fork 0
mirror of https://18126008609:longquanjian123@gitee.com/feigong123/aurask.git synced 2026-04-19 16:18:24 +00:00
Code Issues Actions Releases Activity
0a3f0585f4
aurask/Aurask_Technical_Operations_Plan.md

475 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` 等核心边界。
- 已提供 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
src/aurask/
__init__.py # 包入口，导出 CLI main
__main__.py # python -m aurask 入口
app.py # 应用装配与 demo bootstrap
api.py # 标准库 HTTP 网关
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 / 文档接入适配
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 | `LangflowRuntimeAdapter` 模拟适配层 | 内部 `ClusterIP` Langflow Runtime Pool |
| AnythingLLM | `AnythingLLMAdapter` 模拟适配层 | 内部 `ClusterIP` AnythingLLM API |
| 网关 | Python 标准库 HTTP Server | FastAPI / ASGI + Ingress + HPA |
| 支付 | 人工提交 tx hash 匹配 | TronGrid / Tronscan / 自建节点监听 |
| 观测 | 审计事件写入 store | Prometheus + Loki + Grafana + Alertmanager |
| 部署 | 本地运行 | k3s：`aurask-api` + `aurask-worker` |
## 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 当前代码对应
- 套餐定义：`src/aurask/plans.py`
- 额度账户：`src/aurask/quota.py`
- 订单与权益：`src/aurask/billing.py`
- 使用记录：`src/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>
Reference in New Issue View Git Blame Copy Permalink