# metaguard

**Repository Path**: ajun333/metaguard

## Basic Information

- **Project Name**: metaguard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 领狐网关管理平台

基于 MySQL 的元数据小表快照与快速恢复平台。

## 技术栈

- 后端：FastAPI + SQLAlchemy 2.0 + APScheduler + MySQL
- 前端：React + TypeScript + Vite + Ant Design + React Router + TanStack Query
- 鉴权：内置登录 + 本系统签发 JWT Bearer Token
- 权限：用户 / 角色 / 菜单 / 动作权限
- 告警：钉钉机器人

## 目录

```text
backend/   FastAPI 后端，含 Dockerfile 和 requirements.txt
frontend/  React 前端，含 Dockerfile 和 Nginx 配置
metadata-guard-platform-design.md  设计方案
ARCHITECTURE_AND_FLOWS.md  架构设计图与运转流程图
DEPLOYMENT_RAINBOND.md  Rainbond 部署清单
```

## 后端启动

```powershell
cd backend
copy .env.example .env
python -m uvicorn app.main:app --reload
```

## 环境变量加载策略

- `.env`、`backend/.env`、`frontend/.env.local` 都已在 `.gitignore` 中忽略，不应提交真实配置。
- 后端本地开发默认读取 `backend/.env`。
- 机器或容器环境变量优先级更高；如果同名变量已经存在，`.env` 不会覆盖它。
- 测试/生产环境建议不要放置 `.env` 文件，直接通过部署平台、系统环境变量或 Secret 注入配置。
- 测试/生产可设置 `MG_ENV_FILE_ENABLED=false`，强制后端完全不读取 `backend/.env`。

示例：

```text
MG_APP_ENV=test
MG_ENV_FILE_ENABLED=false
MG_PLATFORM_DB_HOST=...
MG_PLATFORM_DB_USERNAME=...
MG_PLATFORM_DB_PASSWORD=...
MG_AUTH_JWT_SECRET=...
```

初始化平台库执行唯一脚本：

```text
backend/app/sql/001_init.sql
```

这个脚本会创建 `metadata_guard_platform` 数据库以及当前版本所需的全部平台表、索引和外键约束。新项目开发环境只需要执行这一份 SQL。

服务启动时会根据环境变量初始化默认管理员：

```text
MG_BOOTSTRAP_ADMIN_USERNAME=admin
MG_BOOTSTRAP_ADMIN_PASSWORD=admin123
```

首次登录后建议立刻修改默认密码，或在启动前通过环境变量换成强密码。

如果忘记管理员密码，可以在后端目录执行：

```powershell
python reset_admin.py --username admin --password 新密码
```

脚本会创建或重置该用户，并自动绑定 `admin` 角色。

菜单权限、内置 `admin` 角色和默认管理员用户由服务启动时根据环境变量自动初始化，不固化在 SQL 中。

本地开发也可以临时设置：

```text
MG_AUTO_CREATE_TABLES=true
MG_AUTO_MIGRATE_SCHEMA=true
```

## 前端启动

```powershell
cd frontend
npm.cmd install
npm.cmd run dev
```

前端默认请求：

```text
http://localhost:8000/api
```

可通过 `.env.local` 覆盖：

```text
VITE_API_BASE_URL=http://localhost:8000/api
```

## 删除语义

- 数据源、保护表、用户、角色、菜单权限均走逻辑删除，接口会将 `status` 更新为 `deleted`，列表默认隐藏。
- 删除数据源前会检查是否仍被未删除的保护表引用。
- 删除菜单权限前会检查是否存在未删除子菜单/动作权限，或是否仍分配给角色。
- 删除角色前会检查是否仍分配给未删除用户；内置 `admin` 角色不能删除。
- 删除用户前会检查是否为当前登录用户；当前登录用户不能删除自己。
- 删除保护表前会检查是否存在运行中的备份或恢复任务。
- 快照、恢复记录、审计日志、告警事件属于历史留痕页面，默认只读，不提供编辑或删除。
- 快照清理不是删除快照记录，而是清理过期业务库快照表，并将快照状态标记为 `cleaned`。
- 已逻辑删除记录仍保留原唯一编码或名称占用，避免审计记录和历史引用失真。

## 关键安全约束

- 平台库不保存业务库账号密码值，只保存环境变量名。
- 业务库账号变量遵循 `MG_DS_{DATASOURCE_CODE}_USERNAME` / `MG_DS_{DATASOURCE_CODE}_PASSWORD`。
- 恢复必须先 dry-run，再输入 `确认恢复`。
- MVP 不支持外键表、触发器表和超出行数上限的大表。