# yunviewer

**Repository Path**: grepsu/yunviewer

## Basic Information

- **Project Name**: yunviewer
- **Description**: 以只读的形式对多公有云多账号的资源消耗状态进行集中展示和产生相应报表
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 北斗云鉴 - 多云资源视图管理平台

轻量级多云资源状态查看与管理工具，支持阿里云、腾讯云、UCloud、华为云。Python + Flask + SQLite 后端，Vue 3 + Element Plus（soybean-admin 风格）前端。

## ✨ 功能

- **多云统一管理** — 阿里云 / 腾讯云 / UCloud / 华为云，Provider 抽象层统一接入
- **云上主机** — ECS / CVM / UHost / Huawei ECS 列表、状态、开机/关机/重启、资源利用概览
- **数据库实例** — RDS / CDB / UDB / Huawei RDS 实例列表、引擎、规格
- **对象存储** — OSS / COS / UFile / OBS Bucket 列表、存储类型、ACL
- **CDN 管理** — 加速域名列表、CNAME、状态
- **云上网络** — EIP 弹性公网 IP + VPC 专有网络
- **账单管理** — 资金概览(已用/剩余/发票) + 月度汇总 + 按产品统计 + 消费趋势图
- **定时同步** — APScheduler 定时拉取所有资源状态
- **Dashboard** — 全资源总数概览 + 状态分布饼图 + 地域资产地图 + 账号资金可视化
- **用户管理** — RBAC（admin/viewer）+ MFA 双因素认证
- **个人信息** — 姓名/手机/邮箱配置 + 密码修改 + MFA 设置
- **系统配置** — 品牌定制、亮色/暗色主题切换、壁纸上传、邮件/告警配置
- **备份设置** — 本地导出/导入 + 网络备份（阿里云 OSS/邮件）+ 定时自动备份
- **导入导出** — 系统配置 + 云账号（含 AK/SK）一键导出/导入，用于备份或迁移
- **地域自动获取** — 云账号配置时通过云厂商 API 动态获取可用地域列表
- **报表输出** — 按月/季/年导出资产+财务 CSV，支持邮件自动发送
- **Docker 部署** — 多阶段构建，Gunicorn 生产服务器
- **Web 在线更新** — 版本检查、代码拉取、数据库迁移、备份恢复（系统设置 → 系统更新 Tab）

## 📋 系统要求

- **操作系统**：Linux（Debian 12+ / Ubuntu 22.04+ 或 RockyLinux 9+ / AlmaLinux 9+）
- **Python**：3.10 - 3.12（推荐 3.12）
- **Node.js**：18+（推荐 20 LTS）
- **内存**：最低 512MB，推荐 1GB+
- **磁盘**：最低 2GB，推荐 5GB+
- **中文字体**：Noto Sans CJK（安装脚本自动安装）

## 🚀 快速开始

### 方式一：一键脚本安装（推荐生产环境）

使用 `install.sh` 脚本自动完成系统依赖安装、Python 虚拟环境创建、前端构建、systemd 服务注册。

```bash
# 一键安装部署（pip 模式）
chmod +x install.sh
./install.sh --pip

# 或使用 Poetry 安装
./install.sh --poetry

# 跳过前端构建（已有构建产物时）
./install.sh --pip --skip-frontend

# 安装 systemd 服务（需 root 权限）
sudo ./install.sh --install-service

# 服务管理
sudo systemctl start yunviewer    # 启动服务
sudo systemctl stop yunviewer     # 停止服务
sudo systemctl restart yunviewer  # 重启服务
sudo systemctl status yunviewer   # 查看状态
sudo systemctl enable yunviewer   # 开机自启

# 卸载程序
sudo ./install.sh --uninstall

# 查看帮助
./install.sh --help

# 访问
# http://<服务器IP>:5000
# 默认账号: admin / admin123
```

**特点**：
- 自动检测 Debian/Ubuntu 或 RockyLinux/AlmaLinux 环境
- 自动安装完整功能所需的系统依赖（gcc、Pango、Cairo、SQLCipher 等）
- 创建 systemd 服务，支持开机自启
- 使用 Gunicorn 生产级 WSGI 服务器（4 workers）
- 支持卸载功能，可选择保留数据库和配置文件

**日志输出**：
- 应用日志：`/var/log/yunviewer/yunviewer.log`
- 错误日志：`/var/log/yunviewer/yunviewer_error.log`
- 日志轮转：单个文件最大 10MB，保留 5 个备份
- 实时查看：`tail -f /var/log/yunviewer/yunviewer.log`

### 方式二：本地开发模式

适合开发和测试环境，支持 Gunicorn 生产部署。

#### 1. 安装系统依赖

**Debian/Ubuntu**：
```bash
sudo apt-get update
sudo apt-get install -y gcc pkg-config libcairo2-dev libpango1.0-dev \
    libgirepository1.0-dev libffi-dev python3-dev libjpeg-dev libpng-dev \
    libsqlcipher3 libjpeg-turbo8-dev libsoup-3.0 liblcms2-dev libbrotli-dev
```

**RockyLinux/AlmaLinux**：
```bash
sudo dnf install -y gcc pkg-config cairo-devel pango-devel \
    gobject-introspection-devel libffi-devel python3-devel \
    libjpeg-turbo-devel libpng-devel sqlcipher-devel brotli-devel \
    lcms2-devel libsoup-devel
```

#### 2. 安装 Python 依赖
```bash
pip install -r requirements.txt
cd frontend && npm install && cd ..
```

#### 3. 修改配置
```bash
vim config.toml   # 修改 secret_key 和 jwt_secret
```

#### 4. 启动后端

**开发模式**（Flask 内置服务器）：
```bash
python run.py                      # http://127.0.0.1:5000
```

**生产模式**（Gunicorn）：
```bash
cd frontend && npm run build       # 先构建前端
python run.py --gunicorn           # 使用 Gunicorn WSGI 服务器
```

#### 5. 启动前端（新终端）
```bash
cd frontend && npm run dev         # http://localhost:3000
```

#### 6. 登录
```
# Demo账号: admin / 密码: admin123
```

### 方式三：生产环境启动（Gunicorn）

使用 `prodrun.sh` 脚本快速启动生产环境，支持自定义绑定地址和 worker 数量。

```bash
# 默认启动（127.0.0.1:5000, 2 workers）
chmod +x prodrun.sh
./prodrun.sh

# 自定义绑定地址和 worker 数
./prodrun.sh -b 0.0.0.0:8080 -w 4

# 查看帮助
./prodrun.sh --help
```

**参数说明**：
- `-b, --bind ADDRESS`：绑定地址（如 `0.0.0.0:8080`）
- `-w, --workers N`：Worker 进程数（默认从 config.toml 读取，否则 2）
- `-t, --threads N`：Worker 线程数（默认从 config.toml 读取，否则 2）

**特点**：
- 自动检测并激活 Python 虚拟环境
- 支持从 `config.toml` 读取配置
- 优雅重启支持（`kill -s HUP $MAINPID`）
- 适合临时生产环境或测试部署

**前置要求**：
- 已执行前端构建：`cd frontend && npm run build`
- 已安装 Gunicorn：`pip install gunicorn`

### 方式四：Docker 部署

```bash
docker build -t yunviewer .
docker run -d \
  -p 5000:5000 \
  -v $(pwd)/data:/app/instance \
  --name yunviewer \
  yunviewer
# 访问 http://localhost:5000
```

**特点**：
- 多阶段构建，镜像体积小
- 内置 Gunicorn 生产服务器
- 自动安装 WeasyPrint 系统依赖
- 非 root 用户运行，安全性高

## 🏗️ 架构

```
┌────────────── 前端 ──────────────┐
│  Vue 3 + TypeScript + Element Plus│
│  soybean-admin 风格 + 亮色/暗色    │
│  ┌──────────────────────────┐    │
│  │ AppLayout                │    │
│  │ ├─ 可折叠侧边栏          │    │
│  │ ├─ 顶栏 (面包屑+用户)    │    │
│  │ ├─ 标签页               │    │
│  │ ├─ 页面过渡动画         │    │
│  │ └─ 自定义 footer        │    │
│  └──────────────────────────┘    │
│  16 个页面组件                   │
└──────────┬───────────────────────┘
           │ HTTP / JWT
┌──────────▼────── 后端 ───────────┐
│  Flask + SQLAlchemy + SQLite     │
│  ┌──────────────────────────┐    │
│  │ API (14 Blueprints)      │    │
│  ├──────────────────────────┤    │
│  │ Provider 抽象层           │    │
│  │ ├─ AliyunClient          │    │
│  │ ├─ TencentProvider       │    │
│  │ ├─ UCloudProvider        │    │
│  │ └─ HuaweiProvider        │    │
│  ├──────────────────────────┤    │
│  │ APScheduler 定时同步      │    │
│  │ (max_instances=1)        │    │
│  ├──────────────────────────┤    │
│  │ 安全层                    │    │
│  │ ├─ JWT(24h) + MFA        │    │
│  │ ├─ 登录防爆破            │    │
│  │ ├─ AccessKey Fernet加密   │    │
│  │ ├─ 安全响应头            │    │
│  │ └─ 日志脱敏              │    │
│  └──────────────────────────┘    │
└──────────────────────────────────┘
```

### Provider 抽象层

新增云厂商只需实现 `BaseProvider` 的接口：

```
BaseProvider (ABC)
├── verify()              — 连通性验证
├── fetch_regions()       — 获取可用区域
├── sync_servers()        — 同步云主机（含磁盘容量）
├── sync_databases()      — 同步数据库
├── sync_storage()        — 同步对象存储
├── sync_cdn()            — 同步 CDN
├── sync_network()        — 同步网络（EIP + VPC）
├── sync_bills()          — 同步账单
└── get_account_balance() — 查询余额/发票/已用/已开发票
```

## 程序更新

系统支持通过 Web 界面在线更新，自动适配 Docker 和 systemd 部署模式。

### Web 界面更新

**路径**: 系统设置 → 系统更新 Tab

**功能**:
- 版本信息显示（当前版本、构建时间）
- 一键检查更新
- 一键更新（含更新前备份开关）
- 更新进度时间线
- 备份历史管理
- 从备份恢复

### 更新流程

1. **备份** — 自动备份数据库、配置、前端构建产物
2. **拉取代码** — Git pull main 分支最新代码
3. **数据库迁移** — Alembic 自动迁移 schema
4. **重建前端** — Docker 构建或 npm build
5. **重启服务** — 自动适配部署模式

### 备份机制

- 备份位置: `backups/backup_YYYYMMDD_HHMMSS/`
- 默认保留最近 5 个备份
- 支持从任意备份恢复

### 配置项

```toml
[update]
auto_check = true               # 启动时自动检查更新
backup_before_update = true     # 更新前自动备份
update_channel = "stable"       # stable / beta
max_backups = 5                 # 最大保留备份数量
```

## 📦 技术栈

| 层面 | 选型 |
|------|------|
| 后端框架 | Flask |
| ORM | SQLAlchemy + Flask-SQLAlchemy |
| 数据库 | SQLite (WAL 模式) |
| 任务调度 | APScheduler |
| 认证 | JWT (flask-jwt-extended, 24h) |
| MFA | pyotp (TOTP) |
| 加密 | cryptography.fernet |
| 生产服务器 | Gunicorn（支持 systemd/Docker/脚本启动） |
| 前端 | Vue 3 + TypeScript + Vite |
| UI 框架 | Element Plus |
| 主题风格 | soybean-admin (亮色/暗色) |
| 图表 | ECharts |

## 📁 项目结构

```
YunViewer/
├── app/
│   ├── api/           # REST API (14 Blueprints)
│   ├── provider/      # 云厂商 Provider 抽象层（4 个）
│   ├── sync/          # 同步调度
│   ├── services/      # 邮件/告警/报表服务
│   ├── models.py      # 数据模型（10 张表）
│   └── ...
├── frontend/
│   └── src/
│       ├── views/     # 页面组件 (16 个)
│       ├── components/# 布局 + 通用组件
│       ├── api/       # Axios API 封装 (16 个模块)
│       ├── router/    # 路由配置
│       └── styles/    # 亮色/暗色双主题
├── config.toml        # 配置文件（热重载）
├── run.py             # 启动入口（支持 Flask/Gunicorn）
├── prodrun.sh         # 生产环境启动脚本（Gunicorn）
├── install.sh         # 一键安装部署脚本（systemd）
├── Dockerfile         # 多阶段构建
├── SPEC.md            # 详细规格说明
└── README.md
```

## 🔒 安全特性

- JWT 鉴权（24 小时自动过期）
- MFA 双因素认证（TOTP）
- 登录防爆破（5 次失败锁定 5 分钟）
- AccessKey Fernet 对称加密存储
- 安全响应头（X-Content-Type-Options, X-Frame-Options, CSP）
- API 分页上限保护（per_page ≤ 200）
- 日志脱敏（AccessKey ID 掩码）

## 🔧 资源需求

### 最低配置

| 资源 | 要求 | 说明 |
|------|------|------|
| CPU | 1 核 | 同步任务为 I/O 密集型，CPU 占用低 |
| 内存 | 512 MB | Flask + Gunicorn (~150 MB) + 云 SDK (~200 MB) + SQLite/系统开销 (~150 MB) |
| 磁盘 | 2 GB | Python 依赖 (~800 MB，含 WeasyPrint 系统库) + SQLite 数据库 + 前端静态文件 (~10 MB) |
| 网络 | 可访问云厂商 API | 出站 443 端口调用 SDK，入站 5000 端口提供 Web 服务 |

### 推荐配置

| 资源 | 要求 | 说明 |
|------|------|------|
| CPU | 2 核 | 保证同步期间 API 响应流畅 |
| 内存 | 1 GB | 多云厂商同时同步时内存峰值约 500-600 MB |
| 磁盘 | 5 GB | 预留数据库增长空间（月均账单数据约 5-20 MB）+ Docker 镜像 (~1.2 GB) |
| 网络 | 带宽 ≥ 1 Mbps | Dashboard 地图 GeoJSON 约 200 KB，首次加载需外网 |

### 资源消耗说明

- **CPU**：日常空闲 <5%；同步期间 10-30%（I/O 等待为主）
- **内存**：Gunicorn 2 workers × 2 threads 约 150 MB；4 个云厂商 SDK 全量加载约 200 MB；SQLite WAL 缓冲约 10 MB
- **磁盘 I/O**：同步时批量写入（DELETE + INSERT），SSD/HDD 均可；WAL 模式下读不阻塞写
- **网络**：每次同步单厂商单区域 API 调用约 10-50 次，数据量 <1 MB；账单同步 12 个月约 5-20 MB

## 📄 License

Apache 2.0