第 4 章

安装、启动与运维

1. 将发布目录中的局域网答题.exe（及同目录随附文件）复制到教师机本地磁盘（建议非 U 盘）。

本页目录

4.1 打包版安装步骤（教师机）

将发布目录中的 局域网答题.exe（及同目录随附文件）复制到教师机本地磁盘（建议非 U 盘）。
双击 exe：程序启动服务并自动打开浏览器后台页面（默认 http://127.0.0.1:8000）。
首次启动会在 exe 同目录生成 config.ini、data/quiz.db、uploads/、excelstore/、运行日志.txt。
若 Windows 防火墙弹出提示，选择"允许访问专用网络"，否则学生机无法连接。
后台页面会显示局域网访问地址（形如 http://10.193.191.52:8000），将其与"考试码/房间码"一并告知学生。

4.2 源码运行

# 1) 准备环境（Python 3.8+ 均可，推荐与打包一致的版本）
pip install fastapi==0.110.0 "uvicorn[standard]==0.29.0" pydantic==2.6.4 \
            starlette==0.36.3 websockets==12.0 python-dotenv==1.0.1 openpyxl
# 2) 启动
python main.py
# 3) 可选：指定端口与数据库（环境变量优先于配置文件）
$env:QUIZ_PORT=8010; $env:DB_PATH="D:\data\quiz.db"; python main.py

4.3 启动与访问

对象	地址
教师后台（实时场控）	`http://教师机IP:8000/admin`
题库与组卷	`http://教师机IP:8000/qbank`
学生答题现场	`http://教师机IP:8000/`
整卷测验	`http://教师机IP:8000/exam?code=XXXXXX`
健康检查	`http://教师机IP:8000/healthz`（返回 200 即服务正常）
存活标识（单实例检测）	`http://教师机IP:8000/api/svc/ping`

4.4 端口策略与占用排查

默认端口 8000，绝不自动顺延；同一时刻仅允许一个实例（重复双击只会打开页面）。
端口读取优先级：

运行形态	优先级（高 → 低）
打包 exe	`QUIZ_FORCE_PORT` → `config.ini [app] port` → 8000
源码运行	`QUIZ_PORT` → `PORT` → 8000

端口被占用时的处理（PowerShell）：

Get-NetTCPConnection -LocalPort 8000 -State Listen    # 谁在监听
netstat -ano | findstr :8000                          # 传统写法
tasklist /FI "PID eq XXXX"                            # 进程名
taskkill /F /T /PID XXXX                              # 结束进程树

TIME_WAIT 不是占用（PID=0，2–4 分钟自愈），只认 LISTENING 行。首选做法：双击 exe 同目录的 一键关闭服务.bat（可带端口参数，如 一键关闭服务.bat 8010），它会结束占用进程、清理残留 exe 父子进程与 %TEMP%\_MEI* 解包目录并复查端口。

4.5 关闭服务

形态	操作
打包版	页面「关闭服务」按钮，或双击 `一键关闭服务.bat`
源码运行	终端 `Ctrl+C`
Windows 进程残留	任务管理器结束 `局域网答题.exe`（或对应 python 进程）

4.6 配置文件（config.ini）

config.ini 是软件唯一配置文件，位于 exe 同目录（源码模式为项目根），首启自动生成、UTF-8 编码、记事本即可编辑，修改后重启生效。完整键值见附录 A，要点：

[app] port：服务端口；[app] name / copyright：页脚展示；
[app] behind_proxy / proxy_trusted_hosts：反向代理部署开关与受信代理地址；
[database] path / backup_keep_days：数据库位置与备份保留天数；
[update] manifest_url / manifest_hosts / allow_insecure_http：更新源与安全口径；
[log] level：日志级别（默认 INFO）。

4.7 环境变量

见附录 B。优先级：环境变量 > config.ini > 内置默认值。

4.8 数据备份与恢复

自动备份：数据库目录下 backup/ 由程序按 backup_keep_days 保留（默认 30 天），后台「备份管理」可查看/删除/立即备份。
手工备份：python tools/db_backup.py backup 生成 JSON + SQL 全量快照。
直接拷贝的正确姿势：服务运行中不要只拷 quiz.db；应 quiz.db + quiz.db-wal + quiz.db-shm 三件一起拷，或先「关闭服务」（退出前会做 wal_checkpoint(TRUNCATE)）。
恢复：关闭服务 → 用备份文件替换 quiz.db（同时删除残留 -wal/-shm）→ 重新启动。

4.9 日志与排障

日志文件：运行日志.txt（exe 同目录；源码模式项目根），单文件 2MB 轮转、保留 5 份备份。
级别：config.ini [log] level 或环境变量 QUIZ_LOG_LEVEL，默认 INFO；排查时改 DEBUG（会记录每个请求的进出），查完务必改回 INFO。
日志对 password / token / cookie / code 等键名自动打码。
常用检索：

Select-String -Path 运行日志.txt -Pattern '\[draw\]'      # 抽题全生命周期
Select-String -Path 运行日志.txt -Pattern 'ok=0'          # 失败记录
Select-String -Path 运行日志.txt -Pattern 'room=DM3001'   # 指定房间