# 翠鹃镜观

**Repository Path**: grepsu/yunLens

## Basic Information

- **Project Name**: 翠鹃镜观
- **Description**: 实现多厂商多云资源汇聚展示
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!--
  @repo https://gitee.com/grepsu/yunLens
  @license AGPL-3.0
-->
# 翠鹃镜观 (yunLens) · 多云成本可视化与 FinOps 平台

开源、自部署、AI 原生的多云成本管理平台。如翠鹃瞭望，精准洞察多云环境中的每一分成本。

[![License](https://img.shields.io/badge/license-AGPL%20v3-green)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.12+-blue)](https://python.org)
[![Nuxt](https://img.shields.io/badge/nuxt-3.x-00DC82)](https://nuxt.com)

## 核心价值

| 价值点 | 说明 |
|--------|------|
| **统一视图** | 一个平台看阿里云/UCloud/腾讯云/华为云/AWS 全部账单 |
| **数据不出门** | 开源自部署，账单数据留在企业自己的服务器上 |
| **AI 原生** | DeepSeek/OpenAI 集成，自然语言查成本 + 智能异常解读 |
| **轻量级** | SQLite 即可运行，2C2G 服务器够用，不需要 K8s/Prometheus |
| **国内云优先** | 深度支持阿里云/UCloud/火山引擎/腾讯云/华为云账单格式 |

## 快速开始

### 开发模式

```bash
# 后端 API :5000
cd backend
pip install -r requirements.txt
python3 app.py

# 前端 :3000（另一个终端）
cd frontend
npm install --legacy-peer-deps
npm run dev
```

### Docker 部署

```bash
# 复制环境变量并编辑
cp .env.example .env

# 一键启动（4 容器：API + Celery Worker + Celery Beat + Redis）
docker compose up -d

# 查看状态
docker compose ps

# 停止
docker compose down
```

## 功能模块

| 模块 | 路径 | 说明 |
|------|------|------|
| **仪表盘** | `/dashboard` | 单云/多云双模式，Bento Grid 布局，自动切换 |
| **成本分析** | `/cost-explorer` | 多维度下钻（时间/云平台/服务/区域/标签） |
| **资源清单** | `/resources` | 多云资源统一视图 + 闲置检测 |
| **优化建议** | `/optimization` | AI 驱动的省钱建议（RI推荐/降配/清理） |
| **预算管理** | `/budget` | 多维度预算 + 实时进度 + 线性预测告警 |
| **账单明细** | `/billing` | 原始账单查询 + CSV 流式导出 |
| **成本报告** | `/reports` | 预置模板 + 定时发送 + 资产/财务 CSV 导出 |
| **发票管理** | `/invoice` | 各云平台发票追踪 + 待开提醒 + CSV 导入 |
| **云账号** | `/accounts` | API 凭证管理 + AES-256 加密 + 备份导入/导出 |
| **AI 查询** | 仪表盘内嵌 | 自然语言→SQL→AI 解读（实验性功能） |
| **系统设置** | `/settings` | 个人信息 + 用户管理 + 备份 + 导入导出 + 在线更新 |

## v0.2 新增

| 功能 | 说明 |
|------|------|
| **RBAC 用户管理** | admin/viewer 角色，默认 `admin/admin123` |
| **个人信息** | 姓名/手机/邮箱 + 密码修改 + TOTP MFA |
| **定时同步** | APScheduler — 每日资源同步 + 每周清理 + 自动备份 |
| **备份设置** | 本地/邮件备份 + 定时自动备份配置 |
| **一键导入导出** | 系统配置 + 云账号（AK/SK）+ 用户 JSON 导出/导入 |
| **报表 CSV 导出** | 按账号 + 月/季/年导出资产/财务汇总 |
| **Web 在线更新** | 版本检查 + git pull + DB 迁移 + 自动备份 |

## v0.3 新增

| 功能 | 说明 |
|------|------|
| **官方 SDK 集成** | 阿里云 BSSOpenAPI SDK + UCloud SDK，签名鉴权由 SDK 处理 |
| **前端字体自托管** | fontsource 字体包，无 CDN 依赖 |
| **Docker 阿里云镜像** | apt/pip/npm 全部使用阿里云镜像加速构建 |
| **备份邮件发送** | SMTP 配置 + 备份附件发送 + 测试邮件 |
| **导航告警铃铛** | 未读告警角标 + 下拉面板 + 标记已读/全部已读 |

## 技术栈

| 层 | 技术 |
|----|------|
| **后端** | Python 3.12 + Flask 3 + gunicorn + Celery (Redis) |
| **前端** | Nuxt 3 (SSG) + Nuxt UI v3 + Tailwind CSS v4 |
| **数据库** | SQLite (WAL) / 可切换 PostgreSQL |
| **云 SDK** | 阿里云 BSSOpenAPI SDK + UCloud Python SDK |
| **认证** | Session-based RBAC + TOTP MFA |
| **加密** | AES-256 Fernet（云账号凭证） |
| **AI** | DeepSeek / OpenAI / Ollama 兼容 |
| **部署** | Docker Compose (阿里云镜像加速) |

## 支持的云平台

| 云平台 | 状态 | 接入方式 |
|--------|------|----------|
| 阿里云 | ✅ | 官方 BSSOpenAPI SDK + CSV 导入 |
| UCloud | ✅ | 官方 SDK + CSV 导入 |
| 手动 CSV | ✅ | 通用模板兆底 |
| 火山引擎 | ⏳ Phase 2 | BSS API + 账单导出 |
| 腾讯云 | ⏳ Phase 3 | BSS API |
| 华为云 | ⏳ Phase 3 | BSS API |
| AWS | ⏳ Phase 4 | Cost Explorer API |

## 项目结构

```
backend/
├── app.py                  # Flask 工厂 + Session 认证 + SPA fallback
├── config.py               # 环境变量集中配置（YUNLENS_* 前缀）
├── errors.py               # ErrorCode + ServiceResult[T]
├── schemas.py              # Pydantic v2 请求校验
├── models.py               # SQLite WAL + 10 表 + 迁移管理
├── celery_app.py           # Celery 实例 + 显式任务注册
├── ai.py                   # DeepSeek/OpenAI 调用封装
├── adapters/               # 多云适配器（官方 SDK）
│   ├── aliyun.py           # 阿里云 BSSOpenAPI SDK
│   ├── ucloud.py           # UCloud SDK
│   └── csv_import.py       # CSV 导入
├── blueprints/             # 15 个 HTTP 路由模块
├── services/               # 10 个纯业务逻辑模块
├── tasks/                  # Celery 异步任务
├── utils/                  # 文件/安全/限流/加密工具
├── tests/                  # pytest 测试
└── gunicorn.conf.py        # 生产 WSGI 配置

frontend/
├── nuxt.config.ts          # Nuxt 3 (v5) + Nuxt UI v3 + i18n
├── tailwind.config.ts      # 品牌色阶
├── assets/css/main.css     # 自托管字体 + CSS 变量
├── composables/            # useApi / useCostData / useTheme ...
├── api/modules/            # 8 个后端 API 模块
├── components/             # 业务组件 + dashboard
├── pages/                  # 12 个路由页面
├── layouts/default.vue     # 顶部导航 + 告警铃铛 + 状态栏
└── i18n/locales/           # zh.json / en.json
```

## 环境变量

复制 `.env.example` 为 `.env` 并填写：

| 变量 | 必填 | 说明 |
|------|------|------|
| `YUNLENS_SECRET_KEY` | ✅ | Flask Secret Key |
| `YUNLENS_AUTH_USERNAME` | - | 登录用户名（默认 admin） |
| `YUNLENS_AUTH_PASSWORD` | - | 留空 = 跳过认证（开发模式） |
| `YUNLENS_DEEPSEEK_API_KEY` | - | AI 功能（不配则静默降级） |
| `YUNLENS_ALIYUN_KEY` | - | 阿里云 AccessKey ID |
| `YUNLENS_UCLOUD_KEY` | - | UCloud PublicKey |
| `YUNLENS_ENCRYPTION_KEY` | - | 云账号凭证加密密钥（Fernet） |
| `YUNLENS_WEBHOOK_URL` | - | 告警 Webhook 地址 |
| `YUNLENS_SMTP_HOST` | - | 邮件发送 SMTP 主机 |
| `CELERY_BROKER_URL` | - | 默认 `redis://127.0.0.1:6379/0` |
| `DB_PATH` | - | 默认 `backend/data/database.db` |

## 开发命令

```bash
./manage.sh start      # 启动 Flask + Nuxt 开发服务器
./manage.sh stop       # 停止
./manage.sh restart    # 重启
./manage.sh status     # 检查状态（含进程检测）
./manage.sh test       # 运行 pytest
./manage.sh prod       # Gunicorn + Nuxt SSG 生产模式
./manage.sh logs       # 查看日志
./manage.sh help       # 查看所有命令
```

## 许可证

AGPL v3 — 自由使用、修改、分发，衍生作品必须同样以 AGPL 开源。

---

🔭 Made with 翠鹃精神 — 高远视野、精准洞察、自主可控。