可用于地铁线路问题工单的管理与数据统计。支持多线路管理、问题录入、查询、修改、复测,具备用户注册登录、权限控制、数据可视化及响应式设计,适配PC和移动端。【此简介由AI生成】
| Files | Last commit | Last update |
|---|---|---|
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago | ||
| 10 months ago |
地铁线路问题工单填报系统
基于 FastAPI 的地铁线路问题工单填报系统,支持多线路管理、问题录入、查询、修改、复测和数据统计功能。
功能特性
- ✅ 用户注册和登录(管理员账号:admin/123)
- ✅ 多Excel文件和多Sheet(线路)支持
- ✅ 问题录入、查询、修改、复测
- ✅ 数据统计可视化
- ✅ 响应式设计(支持PC和移动端)
- ✅ 权限控制(管理员可修改和复测)
- ✅ 双击表格行查看详情
- ✅ 问题详情卡片分区展示,支持滚动
技术栈
- 后端: FastAPI
- 前端: Jinja2模板 + HTML/CSS/JavaScript
- 数据处理: pandas, openpyxl
- 环境管理: UV
安装和运行
前置要求
- Python 3.13+
- UV 包管理器(推荐使用官方安装脚本)
1. 安装 UV
Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Linux/Mac:
curl -LsSf https://astral.sh/uv/install.sh | sh
安装后,将 UV 添加到 PATH(Linux/Mac 通常会自动添加,或手动添加到 ~/.bashrc 或 ~/.zshrc):
export PATH="$HOME/.cargo/bin:$PATH"
其他安装方式:
# 使用 pip 安装
pip install uv
# 或
pip3 install uv
# 使用 pipx 安装
pipx install uv
2. 安装项目依赖
cd FaultRecord
uv sync
3. 准备 Excel 文件
将 Excel 文件(.xlsx 格式)放在项目根目录下。每个 Excel 文件的每个 Sheet 代表一条线路。
Excel 文件应包含以下列:
- 序号
- 问题分类(平台新需求、平台问题(实施)、平台问题(开发)、平台缺失(开发)、平台缺失(实施))
- 测试时间
- 系统
- 设备名称
- 问题描述
- 整改责任人
- 问题分析
- 截止处理时间
- 整改结果
- 第一次整改时间
- 第二次整改时间
- 第三次整改时间
- 复测结果
- 第一次复测时间
- 第一次复测说明
- 第二次复测时间
- 第二次复测说明
- 第三次复测时间
- 第三次复测说明
- 备注
4. 运行项目
Windows 开发模式(前台运行)
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8010
或者直接运行:
uv run python app/main.py
Linux 后台启动
项目提供了多种 Linux 后台启动方式:
方式一:使用启动脚本(推荐,简单快捷)
# 项目目录
cd FaultRecord
# 赋予执行权限
chmod +x start.sh stop.sh restart.sh
# 启动应用
./start.sh
# 停止应用
./stop.sh
# 重启应用
./restart.sh
启动后,应用会在后台运行,日志保存在 logs/app.log,PID 保存在 faultrecord.pid。
方式二:使用 systemd(推荐生产环境)
systemd 是 Linux 系统的服务管理器,适合生产环境使用,支持开机自启、自动重启等功能。
-
编辑服务文件:
nano faultrecord.service修改以下配置:
WorkingDirectory: 设置为项目实际路径(如/home/user/FaultRecord)User和Group: 设置为运行应用的用户和组(如www-data或你的用户名)ExecStart: 设置为start-service.sh的完整路径Environment: 如果需要,添加用户本地 bin 目录到 PATH(如/home/USER/.local/bin)
示例配置:
WorkingDirectory=/home/user/FaultRecord User=user Group=user Environment="PATH=/usr/local/bin:/usr/bin:/bin:/home/user/.local/bin" ExecStart=/home/user/FaultRecord/start-service.sh -
赋予启动脚本执行权限:
chmod +x start-service.sh -
安装服务:
sudo cp faultrecord.service /etc/systemd/system/ sudo systemctl daemon-reload -
启动服务:
sudo systemctl start faultrecord sudo systemctl enable faultrecord # 设置开机自启 -
管理服务:
# 查看状态 sudo systemctl status faultrecord # 停止服务 sudo systemctl stop faultrecord # 重启服务 sudo systemctl restart faultrecord # 查看日志 sudo journalctl -u faultrecord -f # 查看最近 100 行日志 sudo journalctl -u faultrecord -n 100
方式三:使用 nohup(临时使用)
适合临时测试或快速启动:
# 创建日志目录
mkdir -p logs
# 后台启动
nohup uv run uvicorn app.main:app --host 0.0.0.0 --port 8010 > logs/app.log 2>&1 &
# 查看进程
ps aux | grep uvicorn
# 查看日志
tail -f logs/app.log
# 停止(需要先找到 PID)
kill <PID>
方式四:使用 screen 或 tmux(开发/调试)
适合需要交互式调试的场景:
使用 screen:
# 创建新的 screen 会话
screen -S faultrecord
# 启动应用
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010
# 退出 screen(应用继续运行):按 Ctrl+A,然后按 D
# 重新连接
screen -r faultrecord
# 列出所有 screen 会话
screen -ls
# 终止 screen 会话
screen -X -S faultrecord quit
使用 tmux:
# 创建新的 tmux 会话
tmux new -s faultrecord
# 启动应用
uv run uvicorn app.main:app --host 0.0.0.0 --port 8010
# 退出 tmux(应用继续运行):按 Ctrl+B,然后按 D
# 重新连接
tmux attach -t faultrecord
# 列出所有 tmux 会话
tmux ls
# 终止 tmux 会话
tmux kill-session -t faultrecord
5. 防火墙配置
如果需要在其他机器访问,需要开放端口:
# Ubuntu/Debian (ufw)
sudo ufw allow 8010/tcp
# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=8010/tcp
sudo firewall-cmd --reload
# 或者使用 iptables
sudo iptables -A INPUT -p tcp --dport 8010 -j ACCEPT
6. 访问系统
启动成功后,在浏览器访问:
- 本地访问:http://localhost:8010
- 远程访问:http://<服务器IP>:8010
默认管理员账号:
- 用户名:
admin - 密码:
123
故障排查
检查应用是否运行
# 使用启动脚本时
ps aux | grep uvicorn
cat faultrecord.pid
# 使用 systemd 时
sudo systemctl status faultrecord
查看日志
# 启动脚本日志
tail -f logs/app.log
# systemd 日志
sudo journalctl -u faultrecord -f
检查端口占用
netstat -tlnp | grep 8010
# 或
lsof -i :8010
检查 UV 是否正确安装
which uv
uv --version
检查依赖是否正确安装
uv sync
CSS样式未生效问题
如果在Linux(如树莓派)上部署后,发现样式没有更新,通常是浏览器缓存问题。
解决方案
方法一:强制刷新浏览器(推荐)
-
Chrome/Edge浏览器:
- Windows/Linux: 按
Ctrl + Shift + R或Ctrl + F5 - Mac: 按
Cmd + Shift + R
- Windows/Linux: 按
-
Firefox浏览器:
- Windows/Linux: 按
Ctrl + Shift + R或Ctrl + F5 - Mac: 按
Cmd + Shift + R
- Windows/Linux: 按
-
Safari浏览器:
- Mac: 按
Cmd + Option + R
- Mac: 按
方法二:清除浏览器缓存
- Chrome/Edge:按
F12打开开发者工具,右键点击刷新按钮,选择"清空缓存并硬性重新加载" - Firefox:按
Ctrl + Shift + Delete,选择"缓存",点击"立即清除" - Safari:菜单栏 → 开发 → 清空缓存
方法三:重启服务
如果修改了CSS文件,需要重启服务:
# 使用启动脚本
./restart.sh
# 或使用systemd
sudo systemctl restart faultrecord
方法四:验证CSS是否加载
- 打开浏览器开发者工具(F12)
- 切换到"网络"(Network)标签
- 刷新页面
- 查找
style.css文件 - 检查状态码应该是
200,响应头中应该有正确的Content-Type: text/css
系统已自动添加CSS版本控制功能,每次CSS文件更新后,版本号会自动更新,浏览器会加载最新的CSS文件。
打包(Windows)
项目支持使用PyInstaller打包成Windows可执行文件(带命令行窗口)。
打包步骤
- 安装开发依赖(包含PyInstaller):
uv sync --extra dev
- 执行打包:
Windows(推荐):
build.bat
或使用Python脚本:
uv run python build.py
或直接使用PyInstaller:
uv run pyinstaller build.spec --clean --noconfirm
打包完成后,可执行文件位于 dist/FaultRecord.exe
打包后的使用
- 将
FaultRecord.exe复制到目标目录 - 将Excel文件放在与
FaultRecord.exe相同的目录下 - 双击
FaultRecord.exe运行程序 - 程序会显示命令行窗口,显示运行日志
- 浏览器访问:http://localhost:8010
打包配置
- 打包配置文件:
build.spec - 打包脚本:
build.py或build.bat - 命令行窗口:已启用(
console=True)
打包后的程序会自动处理路径:
- 资源文件(模板、静态文件):从临时目录加载
- Excel文件:从可执行文件所在目录加载
- 用户数据(users.json):保存在可执行文件所在目录
项目结构
FaultRecord/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI应用入口
│ ├── config.py # 配置文件
│ ├── models.py # 数据模型
│ ├── auth.py # 用户认证
│ ├── routers/ # 路由模块
│ │ ├── auth.py # 认证路由
│ │ ├── issues.py # 问题管理路由
│ │ └── stats.py # 统计路由
│ ├── templates/ # Jinja2模板
│ │ ├── base.html
│ │ ├── index.html
│ │ ├── stats.html
│ │ ├── login.html
│ │ └── register.html
│ ├── static/ # 静态资源
│ │ ├── css/
│ │ └── js/
│ └── utils/ # 工具模块
│ ├── excel_loader.py # Excel加载器
│ └── validators.py # 数据验证
├── *.xlsx # Excel数据文件
├── pyproject.toml # 项目配置
└── uv.lock # 依赖锁定文件
使用说明
1. 登录/注册
- 首次使用需要注册账号(只能注册普通用户)
- 管理员账号:admin/123(可修改和复测问题)
2. 选择线路
- 进入首页后,先选择Excel文件和Sheet(线路)
- 如果只有一个Excel文件,会自动加载第一个Sheet
3. 问题管理
- 问题录入:点击"问题录入"按钮,填写问题信息
- 查看详情:点击"查看详情"按钮或双击表格行查看完整问题信息
- 修改问题:管理员可点击"修改"按钮修改问题(需管理员权限)
- 复测功能:管理员可点击"复测"按钮录入复测数据(需管理员权限)
4. 查询功能
- 支持按问题分类、系统、测试时间、整改责任人等条件查询
5. 数据统计
- 进入"数据统计"页面查看统计数据
- 统计包括:新增问题数量、复测问题数量、复测闭环数量、处理数量等
代码检测
项目使用 ruff 进行代码检测和格式化:
# 运行代码检测
uv run ruff check app/
# 自动修复可修复的问题
uv run ruff check app/ --fix
# 运行格式化
uv run ruff format app/
# 或使用便捷脚本(Windows)
check.bat
生产环境建议
- 使用 systemd:提供更好的进程管理和监控
- 配置反向代理:使用 Nginx 作为反向代理,提供 HTTPS 支持
- 修改 SECRET_KEY:在
app/config.py中修改SECRET_KEY为随机字符串 - 配置日志轮转:使用
logrotate管理日志文件 - 设置资源限制:在 systemd service 文件中配置
LimitNOFILE等参数 - 定期备份:备份 Excel 文件和
users.json文件
Nginx 反向代理配置示例
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:8010;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
注意事项
- Excel文件修改后会自动保存,请确保文件有写入权限
- 建议定期备份Excel文件
- 生产环境请修改SECRET_KEY(在app/config.py中)
- 用户数据存储在项目根目录的users.json文件中
开发
代码风格
- 遵循 PEP 8 代码风格指南
- 使用类型提示
- 使用 Pydantic 进行数据验证
测试
# 运行开发服务器(自动重载)
uv run uvicorn app.main:app --reload
许可证
MIT License
Introduction
可用于地铁线路问题工单的管理与数据统计。支持多线路管理、问题录入、查询、修改、复测,具备用户注册登录、权限控制、数据可视化及响应式设计,适配PC和移动端。【此简介由AI生成】
Customize your domain