内容
# 别墅运营AI
一款为巴厘岛别墅和酒店物业经理提供的人工智能运营助理。通过与人工智能代理聊天，可以查询预订、管理物业、联系客人并提供分析服务 — 所有这些都可以通过自然语言完成，由LangGraph和MCP提供支持。
**在线演示：** [villaops.esakrissa.com](https://villaops.esakrissa.com)
|
**API 文档：** [villaops.esakrissa.com/docs](https://villaops.esakrissa.com/docs)
---
## 主要功能
- **工具调用的AI聊天** — LangGraph代理连接到8个MCP工具，通过Streamable HTTP流式传输响应
- **完整的SaaS计费** — Stripe Checkout、客户门户、基于webhook的订阅生命周期（免费/专业/商业层）
- **计划限定的使用限制** — 中间件强制执行属性限制、AI查询配额和每个计划的功能访问
- **多提供商OAuth** — Google + GitHub OAuth与电子邮件/密码注册，带有JWT令牌
- **实时分析仪表板** — 入住率、收入趋势和预订图表，内置Recharts
- **多提供商LLM网关** — LiteLLM路由到Gemini（默认），Anthropic和OpenAI作为备用，并缓存响应
- **262个测试，82%覆盖率** — 跨身份验证、计费、代理、MCP工具和API端点的综合测试套件
- **CI/CD与目标部署** — GitHub Actions管道，仅在代码更改时重建和部署服务
- **部署在AWS ECS Fargate上** — 生产基础设施，带有RDS PostgreSQL、ElastiCache Redis和Cloudflare SSL
---
## 截图
| 登陆页面 | 登录（OAuth + 电子邮件） |
|:---:|:---:|
|  |  |
| AI聊天工具调用 | 定价页面 |
|:---:|:---:|
|  |  |
| 物业管理 | 计费和用量 |
|:---:|:---:|
|  |  |
---
## 功能描述
与其处理电子表格和仪表板，不如让物业经理直接询问：
- *"显示明天所有的入住记录"*
- *"为John预订日落别墅，入住时间为2月10-15日"*
- *"这个月的入住率是多少？"*
- *"向明天的抵达者发送入住说明"*
- *"取消预订#1234"*
- *"本周末巴厘岛的天气预报是什么？*
AI代理理解意图，选择正确的MCP工具，执行并通过聊天界面实时流式传输结果。
---
## 架构
### 应用架构
```
┌────────────────────────────────────────────────────────────┐
│ Next.js前端 │
│ │
│ ┌────────┐ ┌────────┐ ┌───────────┐ ┌───────────────┐ │
│ │ 身份验证 │ │定价 │ │ 聊天界面 │ │ 仪表盘 │ │
│ │ 页面 │ │ 页面 │ │ （SSE） │ │ （预订/ │ │
│ │ │ │ │ │ │ │ 分析） │ │
│ └────────┘ └────────┘ └───────────┘ └───────────────┘ │
└────────┬───────────────────────────────────────────────────┘
│ REST + SSE
▼
┌────────────────────────────────────────────────────┐
│ FastAPI后端 │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 身份验证：JWT + Google OAuth + GitHub OAuth │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 计费：Stripe Checkout + Webhooks │ │
│ │ 计划门控中间件（使用限制） │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌────────────────────────────────┐ │
│ │ REST API │ │ 聊天API（SSE流式传输） │ │
│ │ /api/v1 │ │ /api/v1/chat │ │
│ └────┬─────┘ └──────────┬─────────────────────┘ │
│ │ │ │
│ │ ┌──────────▼─────────────────────┐ │
│ │ │ LangGraph代理 │ │
│ │ │ + MCP客户端（Streamable HTTP） │ │
│ │ └──────────┬─────────────────────┘ │
│ │ │ Streamable HTTP │
│ │ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ MCP服务器（/mcp上的Streamable HTTP） │ │
│ │ booking_search | booking_create │ │
│ │ booking_update | booking_analytics │ │
│ │ guest_lookup | property_manage │ │
│ │ send_notification | web_search │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ LiteLLM网关 │ │
│ │ Gemini（默认）→ Claude → GPT │ │
│ │ +缓存 + 成本跟踪 + 备用 │ │
│ └────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘
┌──────────────────┐ ┌────────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │ │ Stripe │
│ （8张表） │ │ （缓存） │ │ 支付 │
└──────────────────┘ └────────────────┘ └─────────────┘
```
### 部署架构
```
Cloudflare（SSL + DNS）
│
▼
┌───────────────────────┐
│ Nginx（ECS Fargate） │
│ 反向代理 │
└──────────┬────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ 后端 │ │ 前端 │ │ MCP服务器 │
│ （FastAPI） │ │ （Next.js） │ │ （FastMCP） │
│ :8000 │ │ :3000 │ │ :8001 │
└──────┬──────┘ └─────────────┘ └──────┬───────┘
│ │
┌──────┴──────┐ ┌──────┴──────┐
│ RDS │ │ ElastiCache │
│ PostgreSQL │ │ Redis │
└─────────────┘ └─────────────┘
服务发现：AWS Cloud Map（villaops.local）
CI/CD：GitHub Actions → ECR → ECS（目标部署）
```
---
## 技术栈
| 层 | 技术 |
|---|---|
| **后端** | Python 3.13+，FastAPI（异步），Pydantic v2 |
| **代理** | LangGraph |
| **工具协议** | MCP（Streamable HTTP传输） |
| **LLM网关** | LiteLLM（默认Gemini，Anthropic + OpenAI备用） |
| **支付** | Stripe（Checkout + Webhooks + 客户门户） |
| **数据库** | PostgreSQL 16 + SQLAlchemy（异步）+ Alembic迁移 |
| **缓存** | Redis 7 |
| **身份验证** | JWT（python-jose）+ Google OAuth + GitHub OAuth（authlib） |
| **前端** | Next.js 16，React 19，TypeScript，Tailwind CSS v4 |
| **图表** | Recharts |
| **测试** | pytest，pytest-asyncio，httpx（262个测试，82%覆盖率） |
| **CI/CD** | GitHub Actions（lint + test + build + 目标部署） |
| **部署** | AWS ECS Fargate + ECR + RDS + ElastiCache + Cloudflare |
| **反向代理** | Nginx（基于路径的路由，通过AWS Cloud Map DNS） |
---
## 定价
| | 免费 | 专业版 | 商业版 |
|---|---|---|---|
| **价格** | $0/月 | $29/月 | $79/月 |
| **属性** | 1 | 5 | 无限制 |
| **AI查询** | 50/月 | 500/月 | 无限制 |
| **分析** | 基础 | 完整 | 完整 + 导出 |
| **通知** | — | 是 | 是 |
---
## 快速开始
### 前提条件
- Docker & Docker Compose
- Python 3.13+
- Node.js 22+
- 至少一个LLM提供商的API密钥（Gemini，Anthropic或OpenAI）
- Stripe账户（测试模式）- 可选，无计费功能时本地开发
### 快速启动（Docker）
1. **克隆仓库**
```bash
git clone https://github.com/esakrissa/villa-ops-ai.git
cd villa-ops-ai
```
2. **配置环境变量**
```bash
cp .env.example .env
# 编辑.env文件，填写您的API密钥、OAuth凭证和Stripe密钥
```
3. **启动所有服务**
```bash
docker-compose up --build
```
这启动了5个服务：FastAPI后端（:8000），MCP服务器（:8001），Next.js前端（:3000），PostgreSQL和Redis。
4. **运行数据库迁移和种子数据**
```bash
docker-compose exec backend alembic upgrade head
docker-compose exec backend python scripts/seed_data.py
```
5. **启动Stripe webhook监听器** （可选，用于计费功能）
```bash
stripe listen --forward-to localhost:8000/api/v1/webhooks/stripe
```
6. **打开应用**
| 服务 | URL |
|---|---|
| 前端 | [http://localhost:3000](http://localhost:3000) |
| API文档（Swagger） | [http://localhost:8000/docs](http://localhost:8000/docs) |
| MCP服务器 | [http://localhost:8001/mcp](http://localhost:8001/mcp) |
### 无Docker运行
<details>
<summary>后端</summary>
```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# 确保本地运行PostgreSQL和Redis
alembic upgrade head
python scripts/seed_data.py
uvicorn app.main:app --reload
```
</details>
<details>
<summary>MCP服务器</summary>
```bash
cd backend
source .venv/bin/activate
python -m app.mcp.server
```
</details>
<details>
<summary>前端</summary>
```bash
cd frontend
npm install
npm run dev
```
</details>
---
## API概述
### 身份验证端点
| 方法 | 端点 | 描述 |
|---|---|---|
| `POST` | `/api/v1/auth/register` | 使用电子邮件/密码注册 |
| `POST` | `/api/v1/auth/login` | 登录，返回JWT |
| `GET` | `/api/v1/auth/google` | Google OAuth重定向 |
| `GET` | `/api/v1/auth/github` | GitHub OAuth重定向 |
| `POST` | `/api/v1/auth/refresh` | 刷新JWT令牌 |
| `GET` | `/api/v1/auth/me` | 当前用户配置文件 |
### 计费端点
| 方法 | 端点 | 认证 | 描述 |
|---|---|---|---|
| `GET` | `/api/v1/billing/plans` | 否 | 列出可用计划（公开） |
| `GET` | `/api/v1/billing/subscription` | 是 | 当前计划 + 使用统计 |
| `POST` | `/api/v1/billing/checkout` | 是 | 创建Stripe Checkout会话 |
| `POST` | `/api/v1/billing/portal` | 是 | 获取Stripe客户门户URL |
| `POST` | `/api/v1/webhooks/stripe` | 否 | Stripe webhook处理程序 |
### REST端点
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` | `/api/v1/properties` | 列出所有属性 |
| `POST` | `/api/v1/properties` | 创建属性（强制执行计划限制） |
| `GET` | `/api/v1/bookings` | 列出预订（带过滤器） |
| `POST` | `/api/v1/bookings` | 创建预订 |
| `PATCH` | `/api/v1/bookings/{id}` | 更新预订 |
| `GET` | `/api/v1/guests` | 列出客人 |
| `GET` | `/api/v1/analytics/occupancy` | 入住率分析 |
### 聊天端点
```
POST /api/v1/chat
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer <jwt-token>
{
"message": "Show me all check-ins for tomorrow",
conversation_id: "optional-uuid"
}
```
流式传输SSE事件与代理响应和工具调用结果。AI查询使用按计划限制。
---
## MCP工具
LangGraph代理通过Streamable HTTP连接到MCP服务器，并访问8种工具：
| 工具 | 描述 |
|---|---|
| `booking_search` | 按日期、客人、属性或状态搜索预订 |
| `booking_create` | 创建带有验证的新预订（可用性 + 冲突检查） |
| `booking_update` | 修改或取消现有预订 |
| `booking_analytics` | 入住率、收入和预订趋势 |
| `guest_lookup` | 搜索客人信息和预订历史 |
| `property_manage` | 检查可用性、阻塞日期、更新价格 |
| `send_notification` | 向客人发送模板邮件（仅限Pro+计划） |
| `web_search` | 通过Exa搜索外部信息（天气、本地活动等） |
---
## 测试
```bash
cd backend
# 运行所有测试
pytest
# 带有覆盖率报告
pytest --cov=app --cov-report=term-missing
# 特定测试套件
pytest tests/test_api/ # API端点
pytest tests/test_auth/ # 身份验证（JWT + OAuth）
pytest tests/test_billing/ # Stripe计费生命周期
pytest tests/test_agent/ # 代理推理 + 工具选择
pytest tests/test_mcp/ # MCP工具边缘情况
pytest tests/test_services/ # 业务逻辑
```
**当前统计：** 262个测试通过，82%代码覆盖率。
---
## 部署
该应用部署在 **AWS ECS Fargate** 上，并通过GitHub Actions进行自动CI/CD。
### 基础设施
| 资源 | 服务 |
|---|---|
| 计算 | AWS ECS Fargate（4个服务：后端，MCP，前端，nginx） |
| 数据库 | AWS RDS PostgreSQL 16 |
| 缓存 | AWS ElastiCache Redis 7 |
| 容器注册表 | AWS ECR（3个仓库） |
| 服务发现 | AWS Cloud Map（`villaops.local`） |
| SSL / DNS | Cloudflare（代理A记录） |
| 反向代理 | Nginx（基于路径的路由，通过AWS Cloud Map DNS） |
| CI/CD | GitHub Actions（2个工作流：`ci.yml` + `deploy.yml`） |
### CI/CD管道
```
推送到main → CI（lint + test + build）→ 部署（目标）
```
- **目标部署** - 仅部署实际更改代码的服务
- **Cloudflare DNS自动更新** - 部署工作流更新A记录，如果nginx公共IP更改
---
## 项目结构
```
villa-ops-ai/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI入口点
│ │ ├── config.py # 设置（pydantic-settings）
│ │ ├── database.py # 异步SQLAlchemy引擎 + 会话
│ │ ├── models/ # 8个SQLAlchemy模型
│ │ ├── schemas/ # Pydantic请求/响应模式
│ │ ├── api/v1/ # REST + Chat + Auth + Billing + Webhook路由器
│ │ ├── auth/ # JWT + OAuth（Google，GitHub）
│ │ ├── billing/ # Stripe（checkout，webhooks，计划门控）
│ │ ├── agent/ # LangGraph代理 + MCP客户端
│ │ ├── mcp/ # MCP服务器（Streamable HTTP）
│ │ │ ├── server.py
│ │ │ └── tools/ # 8个工具模块
│ │ └── services/ # 业务逻辑层
│ ├── tests/ # 262个测试（82%覆盖率）
│ │ ├── conftest.py
│ │ ├── test_api/
│ │ ├── test_auth/
│ │ ├── test_billing/
│ │ ├── test_agent/
│ │ ├── test_mcp/
│ │ └── test_services/
│ ├── scripts/
│ │ └── seed_data.py # 幂等演示数据播种器
│ ├── alembic/ # 数据库迁移
│ ├── Dockerfile
│ ├── pyproject.toml
│ └── alembic.ini
├── frontend/
│ ├── src/
│ │ ├── app/
│ │ │ ├── （auth）/ # 登录，注册，OAuth回调
│ │ │ ├── pricing/ # 公共定价页面
│ │ │ ├── chat/ # 聊天界面（SSE流式传输）
│ │ │ └── dashboard/ # 预订，分析，属性，计费
│ │ ├── components/
│ │ │ ├── auth/ # OAuthButtons，LoginForm，RegisterForm
│ │ │ ├── chat/ # ChatWindow，MessageBubble，ToolCallCard
│ │ │ ├── dashboard/ # BookingTable，OccupancyChart，PropertyCard
│ │ │ ├── billing/ # PricingCard，UsageMeter，PlanBadge
│ │ │ └── ui/ # Header，Sidebar，LoadingSkeleton
│ │ └── lib/ # API客户端，身份验证助手，钩子
│ ├── Dockerfile
│ └── package.json
├── .aws/ # AWS ECS基础设施
│ ├── backend-task-def.json
│ ├── frontend-task-def.json
│ ├── mcp-task-def.json
│ ├── nginx-task-def.json
│ ├── setup-infra.sh
│ └── nginx/ # Nginx配置 + Dockerfile
├── .github/workflows/
│ ├── ci.yml # CI：lint（ruff+mypy）+ 测试 + 构建
│ └── deploy.yml # 部署：目标ECR + ECS + Cloudflare DNS
├── docker-compose.yml # 开发：5个服务（前端 + 后端 + MCP + postgres + redis）
├── .env.example # 环境变量模板
└── README.md
```
---
## 环境变量
所有变量都通过`.env`配置（参见[`.env.example`](.env.example)获取模板）。
| 变量 | 是否必需 | 描述 |
|---|---|---|
| **应用** | | |
| `APP_NAME` | 否 | 应用程序名称（默认为`VillaOps AI`） |
| `DEBUG` | 否 | 启用调试模式（默认为`true`） |
| `ENVIRONMENT` | 否 | `development`或`production` |
| **数据库** | | |
| `DATABASE_URL` | 是 | PostgreSQL异步连接字符串 |
| **缓存** | | |
| `REDIS_URL` | 是 | Redis连接字符串 |
| **身份验证** | | |
| `JWT_SECRET_KEY` | 是 | JWT令牌签名的密钥 |
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | 否 | 访问令牌TTL（默认为`30`） |
| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | 否 | 刷新令牌TTL（默认为`7`） |
| `GOOGLE_CLIENT_ID` | 否 | Google OAuth客户端ID |
| `GOOGLE_CLIENT_SECRET` | 否 | Google OAuth客户端密钥 |
| `GITHUB_CLIENT_ID` | 否 | GitHub OAuth客户端ID |
| `GITHUB_CLIENT_SECRET` | 否 | GitHub OAuth客户端密钥 |
| **Stripe** | | |
| `STRIPE_SECRET_KEY` | 否\* | Stripe密钥（\*需要计费功能） |
| `STRIPE_PUBLISHABLE_KEY` | 否\* | Stripe公开密钥 |
| `STRIPE_WEBHOOK_SECRET` | 否\* | Stripe webhook签名密钥 |
| `STRIPE_PRO_PRICE_ID` | 否\* | Stripe Pro计划价格ID |
| `STRIPE_BUSINESS_PRICE_ID` | 否\* | Stripe商业计划价格ID |
| **LLM** | | |
| `DEFAULT_LLM_MODEL` | 否 | LiteLLM模型字符串（默认为`gemini/gemini-3-flash-preview`） |
| `GEMINI_API_KEY` | 是\*\* | Google Gemini API密钥（\*至少需要一个LLM密钥） |
| `ANTHROPIC_API_KEY` | 否 | Anthropic API密钥（备用） |
| `OPENAI_API_KEY` | 否 | OpenAI API密钥（备用） |
| **Web搜索** | | |
| `EXA_API_KEY` | 否 | Exa API密钥，用于`web_search`工具 |
| **服务** | | |
| `MCP_SERVER_URL` | 是 | MCP服务器URL（默认为`http://localhost:8001/mcp`） |
| `FRONTEND_URL` | 是 | 前端URL，用于CORS和OAuth重定向 |
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器