基于Postgresql的轻量级报表管理系统（内置常用工具集）

报表管理系统 (Report Management System)

基于 FastAPI + Jinja2 + HTMX 的轻量级动态报表平台。通过编写一条 SQL 即可生成带筛选、分页、排序、列展示配置的报表页面，支持多数据源、目录树组织与细粒度权限控制。

---

✨ 功能特性

报表子系统

• 动态报表：一条 SQL 生成一个报表页面，运行时替换 ${date}/${start_date} 等日期变量
• 字段配置：可视化配置列名、对齐、宽度、排序、阈值染色、值映射、下拉/日期筛选
• 多数据源：内置 PostgreSQL，可扩展配置 MySQL / Doris 等外部数据源（含连接测试）
• 目录树：支持多级目录组织报表
• 权限管控：目录级、导航级、报表级三级权限；管理员 / 普通用户角色
• Excel 导出：报表结果一键导出
• 只读校验：执行前强制校验 SQL 仅含 SELECT/WITH，拦截写操作与多语句

工具箱 (Toolbox)

内置常用开发辅助工具，无需额外软件即可完成日常数据处理任务：

工具	说明
地图坐标系转换工具	WGS84、GCJ02、BD09 坐标系互转，适用于地图数据校准与核验
文本批量拼接工具	批量拼接文本前后缀、分隔符和换行，快速生成 SQL 条件或配置片段
时间戳转换工具	秒级、毫秒级时间戳与日期时间互转，并可快速获取当前时间戳
JSON 数据解析工具	解析 JSON 数据，提取关键字段并支持表格化查看
Excel 转 DDL 生成工具	读取 Excel 字段模板，生成 Hive 或 PostgreSQL 建表 DDL（含模板下载）

工具箱通过导航栏"工具箱"入口访问，与报表子系统共用同一套登录与权限体系。

🧱 技术栈

层	技术
后端	FastAPI, Uvicorn
模板	Jinja2
前端交互	HTMX（CDN 加载，见下方说明）
数据库	PostgreSQL（主），可扩展 MySQL / Doris
驱动	psycopg2, PyMySQL
其他	openpyxl（Excel）、itsdangerous（会话签名）、python-multipart

📁 目录结构

.
├── main.py                 # FastAPI 入口
├── config.py               # 配置（从 .env 读取）
├── sql/
│   └── init_schema.sql     # 数据库初始化脚本（含默认管理员）
├── app/
│   ├── auth.py             # 认证 / 密码哈希 (PBKDF2-HMAC-SHA256)
│   ├── database.py         # 数据库连接与游标管理
│   ├── routes/             # 路由：auth / reports / directories / datasources / users / tools
│   └── services/           # 服务层：report / permissions / excel_service
├── templates/
│   ├── tools/              # 工具箱页面模板（5 个工具）
│   └── partials/           # 可复用模板片段
├── static/                # 静态资源 (css/js)
└── resources/             # 模板文件 (template.xlsx，供 Excel→DDL 工具下载)

🚀 快速开始

1. 环境要求

• Python 3.10+
• PostgreSQL 12+

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

复制示例文件并按需修改：

cp .env.example .env

至少需要设置 DB_HOST / DB_USER / DB_PASSWORD / DB_NAME。DB_PASSWORD 不再有默认弱密码，未设置时启动不会报错，但首次访问数据库会明确提示缺少密码。

4. 初始化数据库

在目标 PostgreSQL 中执行初始化脚本（会创建 fast_report schema 及所有表，并写入默认管理员）：

psql -h <DB_HOST> -U <DB_USER> -d <DB_NAME> -f sql/init_schema.sql

默认管理员账号：admin / admin123456（密码以 PBKDF2 哈希存储，非明文）。首次登录后请务必修改密码。

5. 启动

python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8000

访问 http://localhost:8000。健康检查：GET /health。

🖥️ 部署（含内网 / 离线环境）

本系统可部署在无法访问公网的服务器上。以下为离线部署要点：

1. 准备 Python 运行时（断网服务器推荐使用独立路径编译的 3.12）：

   # 在可联网机器下载适配 linux x86_64 的依赖包
   pip download -d ./offline_packages -r requirements.txt \
       --platform linux_x86_64 --only-binary=:all: -i https://pypi.org/simple
   # 断网服务器离线安装
   python3.12 -m pip install --no-index --find-links=./offline_packages -r requirements.txt
   

2. 防火墙放行端口：

   sudo firewall-cmd --permanent --add-port=8000/tcp
   sudo firewall-cmd --reload
   

3. 后台启动：

   nohup python3.12 main.py > app.log 2>&1 &
   

4. 若缺失 pymysql 等某个包，可在联网机器单独 pip download 后上传到 offline_packages 再安装。

⚠️ HTMX 通过 CDN（unpkg.com）加载：内网 / 离线环境会因无法访问 CDN 导致交互失效。建议将 htmx.org@1.9.10 下载到 static/js/vendor/ 并改为本地引用（详见下方「安全与待优化」）。

🔒 安全说明

• 用户密码使用 PBKDF2-HMAC-SHA256（26 万次迭代） 加盐哈希存储，兼容历史 SHA-256 / 明文（登录后自动升级哈希）。
• 报表 SQL 执行前经过 ensure_readonly_sql 校验，仅允许单条 SELECT/WITH，拦截 INSERT/UPDATE/DROP 等写操作与多语句。
• 筛选条件通过 参数化占位符 拼接到外层 WHERE，避免字符串拼接注入。
• SECRET_KEY 未设置时每次启动随机生成（会话会失效），生产环境务必在 .env 中固定。

📄 License

MIT