🏢 CityVistion SAAS 商业化运营技术方案

版本 1.0 | 2026-05-30 | 适用于 CityVistion CGA 引擎平台

SAAS

多租户云原生架构

API

RESTful + WebSocket 服务

微信/支付宝/Stripe 支付

OSS

阿里云对象存储 CDN

📋 目录

执行摘要与商业模式
系统架构总览
后台管理系统 (Admin)
支付系统集成
阿里云 OSS 与 CDN
API 接口服务层
SAAS 多租户架构
计费与订阅系统
用户管理与权限 RBAC
数据库设计
部署与运维方案
安全方案
开发路线图与里程碑

1. 执行摘要与商业模式

1.1 产品定位

CityVistion 是一个基于浏览器的 CGA (Computer Generated Architecture) 规则引擎，支持从 OSM 数据自动生成 3D 建筑模型。商业化目标是将该引擎包装为 SAAS 平台，向以下客户群体提供服务：

城市规划师 / 建筑师：快速生成城市级 3D 场景
游戏开发商：程序化生成游戏内建筑资产
智慧城市项目：数字孪生城市底座
教育培训机构：CityEngine 替代教学工具
开发者：通过 API 集成 CGA 生成能力

1.2 收费模式

套餐	价格	核心权益	目标用户
免费版 (Free)	¥0	5 个项目、基础 CGA 规则、社区支持	个人体验 / 学生
专业版 (Pro)	¥199/月	50 个项目、ESRI.lib 全功能、OSM 批量下载、优先支持	自由职业者 / 小型工作室
团队版 (Team)	¥899/月	无限项目、5 个席位、API 访问、私有规则库	中型设计公司
企业版 (Enterprise)	定制化报价	私有化部署、SLA 保障、专属客户经理、定制开发	大型政企 / 智慧城市
API 按量计费	¥0.5/千次调用	模型生成 API、数据转换 API、场景导出 API	开发者 / 系统集成商

2. 系统架构总览

2.1 技术栈选型

前端

Three.js (3D 渲染引擎)
Vite (构建工具)
Vanilla JS + 模块化架构
CodeMirror (CGA 编辑器)
MapLibre GL (地图组件)

后端

Python FastAPI (主 API 服务)
PostgreSQL + PostGIS (主数据库)
Redis (缓存 / 会话 / 队列)
Celery (异步任务队列)
MinIO / 阿里云 OSS (对象存储)

基础设施

Docker + Docker Compose (开发)
Kubernetes (生产)
Nginx (反向代理 / 负载均衡)
阿里云 ECS / ACK (云服务器)
Prometheus + Grafana (监控)

第三方服务

微信支付 / 支付宝 (国内支付)
Stripe (国际支付)
阿里云 OSS + CDN (静态资源)
SendGrid / 阿里云邮件 (邮件通知)
Sentry (错误追踪)

2.2 架构图

┌─────────────────────────────────────────────────────────────────────────────┐
│                              客户端层 (Client Layer)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Web 浏览器   │  │ 移动 H5     │  │ 第三方系统   │  │ 微信小程序          │ │
│  │ (Three.js)  │  │ (Vue3)      │  │ (API 集成)  │  │ (微信登录+支付)     │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
└─────────┼────────────────┼────────────────┼────────────────────┼────────────┘
          │                │                │                    │
          ▼                ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           接入层 (Gateway Layer)                             │
│  ┌─────────────────────────────────────────────────────────────────────────┐ │
│  │  Nginx (SSL 终止 / WAF / 限流 / 负载均衡)                                │ │
│  │  ├── /api/*  → FastAPI 后端服务                                          │ │
│  │  ├── /ws/*   → WebSocket 实时协作                                        │ │
│  │  ├── /static → 阿里云 CDN / OSS                                         │ │
│  │  └── /admin  → 后台管理系统 (Vue3 SPA)                                   │ │
│  └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         服务层 (Service Layer)                               │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐│
│  │  API Gateway │ │  Auth Service│ │  Billing     │ │  Admin Service       ││
│  │  (Kong/AWS)  │ │  (JWT/OAuth2)│ │  (Stripe/    │ │  (FastAPI + Vue3)    ││
│  │              │ │  微信登录     │ │  微信/支付宝)│ │  后台管理面板        ││
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘│
│         │                │                │                    │            │
│  ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐ ┌──────────▼───────────┐│
│  │  CGA Engine  │ │  Project     │ │  OSM Import  │ │  Notification        ││
│  │  Service     │ │  Service     │ │  Service     │ │  Service             ││
│  │  (模型生成)   │ │  (CRUD)      │ │  (Overpass)  │ │  (邮件/短信/Webhook) ││
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘│
│         │                │                │                    │            │
│  ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐ ┌──────────▼───────────┐│
│  │  File        │ │  Payment     │ │  WebSocket   │ │  Webhook             ││
│  │  Service     │ │  Service     │ │  Service     │ │  Service             ││
│  │  (OSS/MinIO) │ │  (异步回调)   │ │  (协作编辑)  │ │  (事件推送)          ││
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         数据层 (Data Layer)                                  │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐│
│  │ PostgreSQL   │ │ Redis        │ │ 阿里云 OSS   │ │ Elasticsearch        ││
│  │ + PostGIS    │ │ (Cache/Queue)│ │ (模型/贴图)  │ │ (日志/搜索)          ││
│  │ 主数据库     │ │              │ │              │ │                      ││
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘

3. 后台管理系统 (Admin Panel)

3.1 技术选型

后台管理系统采用 Vue 3 + Element Plus + FastAPI 技术栈，独立部署在 /admin 路径下，与主应用分离。

3.2 功能模块

模块	功能	技术实现
仪表盘	实时数据：注册用户数、活跃项目、收入统计、API 调用量	ECharts + Redis 计数器 + PostgreSQL 聚合
用户管理	用户列表、实名认证审核、封禁/解封、角色分配	RBAC + 阿里云实名认证 API
订单与财务	订单列表、退款处理、对账单导出、发票管理	FastAPI + Celery 定时对账
系统配置	支付配置、OSS 配置、邮件模板、定价策略	PostgreSQL config 表 + 前端表单
内容管理	公告发布、帮助文档、CGA 规则模板审核	富文本编辑器 + OSS 图片上传
日志与监控	操作日志、错误日志、API 调用日志、性能监控	Sentry + ELK Stack + Prometheus

3.3 管理界面路由

/admin/dashboard       → 数据仪表盘
/admin/users           → 用户管理
/admin/orders          → 订单管理
/admin/projects        → 项目审核
/admin/config/payment  → 支付配置（微信/支付宝/Stripe）
/admin/config/oss      → 阿里云 OSS 配置
/admin/config/pricing  → 定价策略配置
/admin/logs            → 系统日志
/admin/announcements   → 公告管理

4. 支付系统集成

4.1 微信支付

接入流程

注册微信支付商户号（需企业营业执照）
配置 APIv3 密钥、证书、商户号、AppID
后台配置页面录入：mchid、appid、api_key、证书文件
实现 Native 支付（PC 端扫码）和 JSAPI 支付（微信内 H5）
配置异步回调地址 /api/payment/wechat/notify

核心接口

POST /api/payment/wechat/create    → 创建订单，返回支付二维码
POST /api/payment/wechat/notify    → 微信支付异步回调（幂等处理）
POST /api/payment/wechat/query     → 主动查询订单状态
POST /api/payment/wechat/refund    → 申请退款

4.2 支付宝支付

接入流程

注册支付宝企业账号，开通当面付 / 电脑网站支付
配置应用公钥、应用私钥、支付宝公钥、AppID
后台配置页面录入：app_id、private_key、public_key、alipay_public_key
实现 PC 端扫码支付和手机端 H5 支付
配置异步回调地址 /api/payment/alipay/notify

核心接口

POST /api/payment/alipay/create    → 创建订单，返回支付表单/二维码
POST /api/payment/alipay/notify    → 支付宝异步回调（验签+幂等）
POST /api/payment/alipay/query     → 主动查询订单状态
POST /api/payment/alipay/refund    → 申请退款

4.3 Stripe (国际支付)

POST /api/payment/stripe/create    → 创建 Checkout Session
POST /api/payment/stripe/webhook   → Stripe Webhook 回调
POST /api/payment/stripe/portal    → 客户自助订阅管理 Portal

4.4 支付状态机

[创建订单] → pending → [支付中] → paid → [已支付] → [开通服务]
                    ↘ expired → [已过期] → [自动关单]
                    ↘ refunding → [退款中] → refunded → [已退款]

5. 阿里云 OSS 与 CDN

5.1 架构设计

采用 阿里云 OSS 作为对象存储，阿里云 CDN 加速全球分发。存储内容分类如下：

存储类型	Bucket 命名	存储内容	CDN 加速
用户项目数据	`peyep-projects`	CGA 规则文件、场景 JSON、CEJ 项目文件	否（仅服务端访问）
3D 模型资产	`peyep-assets`	OBJ/GLTF/FBX 导出模型、贴图纹理	是（全球加速）
静态资源	`peyep-static`	JS/CSS/字体、ESRI.lib 规则库、教程图片	是（全站加速 DCDN）
备份归档	`peyep-archive`	数据库备份、日志归档、历史版本	否（低频访问存储）

5.2 后台配置界面

管理员可在后台 /admin/config/oss 配置以下参数：

阿里云 AccessKey ID      → ak_xxxxxxxxxxxxxxxx
阿里云 AccessKey Secret  → [加密存储，仅管理员可见]
OSS Endpoint             → oss-cn-hangzhou.aliyuncs.com
项目数据 Bucket          → peyep-projects
模型资产 Bucket          → peyep-assets
静态资源 Bucket          → peyep-static
CDN 加速域名             → https://cdn.cityvistion.com
CDN HTTPS 证书           → [自动上传/阿里云 SSL 托管]

5.3 文件上传流程

1. 客户端请求上传：POST /api/upload/sign
   → 服务端生成阿里云 STS 临时凭证 + 预签名 URL
2. 客户端直传 OSS：PUT https://peyep-assets.oss-cn.../user123/model.obj?OSSAccessKeyId=...
3. OSS 回调服务端：POST /api/upload/callback
   → 服务端验证签名，记录文件元数据到数据库
4. 客户端获取 CDN URL：https://cdn.cityvistion.com/user123/model.obj

6. API 接口服务层

6.1 API 设计原则

RESTful：资源导向，使用标准 HTTP 方法 (GET/POST/PUT/DELETE)
版本控制：URL 前缀 /api/v1/，支持多版本并行
认证方式：JWT Access Token + Refresh Token，API Key 用于服务端集成
限流策略：按套餐等级限流（免费 100次/小时，Pro 1000次/小时）
响应格式：统一 JSON 格式 {code, message, data, pagination}

6.2 核心 API 列表

接口	方法	说明	计费
/api/v1/auth/register	POST	用户注册	免费
/api/v1/auth/login	POST	用户登录，返回 JWT	免费
/api/v1/projects	CRUD	项目管理	免费
/api/v1/cga/evaluate	POST	执行 CGA 规则，返回 mesh 数据	按次计费
/api/v1/cga/export	POST	导出 OBJ/GLTF/FBX	按次计费
/api/v1/osm/buildings	POST	OSM 建筑数据下载+生成	按面积计费
/api/v1/osm/roads	POST	OSM 道路数据下载	按面积计费
/api/v1/payment/create	POST	创建支付订单	免费
/api/v1/webhooks	CRUD	Webhook 管理	Pro 以上

6.3 API 认证流程

1. 用户登录：POST /api/v1/auth/login → {access_token, refresh_token, expires_in}
2. 请求 API：Header 携带 Authorization: Bearer {access_token}
3. Token 过期：POST /api/v1/auth/refresh → 换取新 access_token
4. API Key 模式：Header 携带 X-API-Key: {api_key}（用于服务端集成）

7. SAAS 多租户架构

7.1 租户隔离策略

采用 共享数据库 + Schema 隔离 的混合模式：

资源类型	隔离方式	说明
数据库表	tenant_id 字段隔离	所有业务表增加 tenant_id，查询自动过滤
文件存储	Bucket 前缀隔离	OSS 路径：/{tenant_id}/projects/{project_id}/...
Redis 缓存	Key 前缀隔离	Key 格式：tenant:{tenant_id}:session:{user_id}
CGA 计算资源	队列隔离	Celery 队列按租户分级，付费用户优先

7.2 租户数据模型

class Tenant(BaseModel):
    id: UUID                        # 租户唯一标识
    name: str                       # 租户名称（企业名）
    slug: str                       # URL 标识，如 acme-corp
    plan: Enum[free, pro, team, enterprise]
    status: Enum[active, suspended, expired]
    settings: JSON                  # 自定义配置（主题、域名等）
    created_at: datetime
    expires_at: datetime            # 套餐到期时间
    max_projects: int               # 项目数量限制
    max_users: int                  # 团队成员限制
    max_storage_gb: float           # 存储空间限制
    api_quota_per_hour: int         # API 限流

8. 计费与订阅系统

8.1 计费模型

采用 订阅制 + 按量计费 的混合模式：

订阅费：按月/年收取固定费用，解锁功能套餐
按量费：超出套餐配额后，按实际使用量计费
预付费：API 调用购买积分包（1000 积分 = ¥50）
后付费：企业客户按月结算账单

8.2 计费事件

事件	计费单位	免费版	专业版	团队版
项目创建	个/月	5	50	无限
CGA 模型生成	次/月	50	500	5000
OSM 数据下载	km²/月	1	10	100
模型导出 (OBJ/GLTF)	次/月	10	100	1000
API 调用	次/月	100	1000	10000
存储空间	GB	1	10	100

8.3 计费引擎实现

# 技术实现
- Redis 计数器：实时统计租户用量（每日/每月重置）
- PostgreSQL billing_events 表：记录每次计费事件
- Celery 定时任务：每日生成用量报告，每月生成账单
- 超额处理：达到 80% 配额时发送预警，达到 100% 时限制服务

9. 用户管理与权限 RBAC

9.1 角色定义

角色	权限
超级管理员 (Super Admin)	全平台管理、租户管理、系统配置、财务数据
租户管理员 (Tenant Admin)	管理团队成员、项目、账单、API Key
开发者 (Developer)	创建/编辑项目、使用 API、导出模型
只读用户 (Viewer)	查看项目、预览模型、下载（受限）
访客 (Guest)	浏览示例、注册账号

9.2 登录方式

邮箱+密码：基础登录，支持验证码
手机号+验证码：国内用户主流方式
微信扫码登录：微信开放平台 OAuth2
GitHub/Google 登录：国际用户
SSO 企业登录：企业版支持 SAML/OIDC 对接企业 AD/LDAP

10. 数据库设计

10.1 核心表结构

-- 租户表
create table tenants (
    id uuid primary key default gen_random_uuid(),
    name varchar(100) not null,
    slug varchar(50) unique not null,
    plan varchar(20) not null default 'free',
    status varchar(20) not null default 'active',
    settings jsonb default '{}',
    created_at timestamptz default now(),
    expires_at timestamptz,
    max_projects int default 5,
    max_users int default 1,
    max_storage_gb float default 1,
    api_quota_per_hour int default 100
);

-- 用户表
create table users (
    id uuid primary key default gen_random_uuid(),
    tenant_id uuid references tenants(id),
    email varchar(255) unique,
    phone varchar(20) unique,
    password_hash varchar(255),
    display_name varchar(100),
    avatar_url varchar(500),
    role varchar(20) default 'developer',
    status varchar(20) default 'active',
    last_login_at timestamptz,
    created_at timestamptz default now()
);

-- 项目表
create table projects (
    id uuid primary key default gen_random_uuid(),
    tenant_id uuid references tenants(id),
    user_id uuid references users(id),
    name varchar(200) not null,
    description text,
    cga_code text,
    scene_data jsonb,
    pts geometry(Polygon, 4326),  -- PostGIS 地理围栏
    status varchar(20) default 'active',
    created_at timestamptz default now(),
    updated_at timestamptz default now()
);

-- 订单表
create table orders (
    id uuid primary key default gen_random_uuid(),
    tenant_id uuid references tenants(id),
    user_id uuid references users(id),
    order_no varchar(50) unique not null,
    product_type varchar(50) not null,  -- subscription / credits / api_call
    plan varchar(20),
    amount decimal(10,2) not null,
    currency varchar(3) default 'CNY',
    payment_method varchar(20),  -- wechat / alipay / stripe
    payment_status varchar(20) default 'pending',
    paid_at timestamptz,
    expires_at timestamptz,
    created_at timestamptz default now()
);

-- 计费事件表
create table billing_events (
    id uuid primary key default gen_random_uuid(),
    tenant_id uuid references tenants(id),
    user_id uuid references users(id),
    event_type varchar(50) not null,  -- cga_eval / osm_download / model_export
    quantity int not null default 1,
    cost decimal(10,4) default 0,
    metadata jsonb default '{}',
    created_at timestamptz default now()
);

-- API Key 表
create table api_keys (
    id uuid primary key default gen_random_uuid(),
    tenant_id uuid references tenants(id),
    user_id uuid references users(id),
    key_hash varchar(255) unique not null,
    name varchar(100),
    permissions jsonb default '[]',
    last_used_at timestamptz,
    expires_at timestamptz,
    created_at timestamptz default now()
);

11. 部署与运维方案

11.1 部署架构

阿里云 ECS (杭州)          阿里云 ECS (新加坡)
┌──────────────────┐      ┌──────────────────┐
│  Nginx (LB)      │◄────►│  Nginx (LB)      │
│  + WAF           │      │  + WAF           │
└────────┬─────────┘      └────────┬─────────┘
         │                         │
    ┌────┴────┐               ┌────┴────┐
    │K8s 集群 │               │K8s 集群 │
    │(3 节点) │               │(2 节点) │
    │         │               │         │
    │Frontend │               │Frontend │
    │API Pod  │               │API Pod  │
    │Worker   │               │Worker   │
    └─────────┘               └─────────┘
         │                         │
    ┌────┴─────────────────────────┴────┐
    │        阿里云 RDS PostgreSQL        │
    │        阿里云 Redis                 │
    │        阿里云 OSS                   │
    └─────────────────────────────────────┘

11.2 CI/CD 流水线

GitHub Push → GitHub Actions → 单元测试 → 构建 Docker 镜像 → 推送阿里云镜像仓库
                                                        ↓
                                                   蓝绿部署
                                                        ↓
                                               健康检查 → 流量切换
                                                        ↓
                                               Prometheus 监控报警

11.3 监控告警

监控项	工具	告警阈值
API 响应时间	Prometheus + Grafana	P95 > 500ms 持续 5 分钟
错误率	Sentry + Prometheus	5xx 错误率 > 1%
数据库连接	RDS 监控	连接数 > 80%
磁盘空间	阿里云监控	使用率 > 85%
SSL 证书	Prometheus Blackbox	到期前 30 天告警

12. 安全方案

12.1 数据安全

传输加密：全站 HTTPS (TLS 1.3)，HSTS 头
存储加密：数据库 TDE 加密，OSS 服务端加密 (SSE)
密钥管理：阿里云 KMS 托管密钥，定期轮换
备份策略：数据库每日自动备份，保留 30 天；异地容灾
数据脱敏：日志中隐藏敏感信息（手机号、身份证号）

12.2 应用安全

认证安全：JWT 短有效期 (15min) + Refresh Token (7天)
防暴力破解：登录失败 5 次锁定 15 分钟
SQL 注入防护：参数化查询 + ORM
XSS 防护：输入过滤 + CSP 策略
CSRF 防护：SameSite Cookie + CSRF Token
API 限流：Redis 令牌桶算法，按租户+接口限流

12.3 合规

等保三级：按中国网络安全等级保护三级要求建设
GDPR：支持用户数据导出和删除 (Right to be Forgotten)
ICP 备案：域名完成 ICP 备案
隐私政策：完善的用户隐私协议和 Cookie 政策

13. 开发路线图与里程碑

Phase 1：基础平台 (MVP) — 2 个月

用户注册/登录/找回密码
项目 CRUD + CGA 编辑器
微信支付 + 支付宝支付
基础套餐（免费/专业）
阿里云 OSS 文件存储

Phase 2：团队协同 — 1 个月

团队成员邀请与管理
项目权限控制（读写/只读）
实时协作编辑 (WebSocket)
版本历史与回滚
团队版套餐上线

Phase 3：API 开放 — 1 个月

RESTful API 全量开放
API Key 管理 + 文档
Webhook 事件推送
SDK 开发 (Python/JavaScript)
按量计费模式

Phase 4：企业级 — 2 个月

后台管理系统 (Admin Panel)
SSO / SAML 企业登录
私有化部署方案
SLA 保障 + 专属客服
高级分析报表

Phase 5：生态建设 — 持续

CGA 规则市场（买卖规则模板）
3D 模型资产市场
插件系统（Blender/Unity/Unreal 导出）
AI 辅助规则生成
国际化（多语言 / 多区域部署）

💡 总结

CityVistion SAAS 化方案以 多租户架构 为基础，通过 API 服务层 开放核心 CGA 引擎能力，结合 微信/支付宝/Stripe 多渠道支付、阿里云 OSS+CDN 全球分发，构建完整的商业化平台。后台管理系统让运营团队能够灵活配置定价策略、监控平台健康、管理用户与订单。