# exam-system

**Repository Path**: sywxsoft/exam-system

## Basic Information

- **Project Name**: exam-system
- **Description**: 单机版 Flask 考试出卷系统：题库管理、富文本图片题干、自动/手动组卷、Word 模板导出、Excel 批量导入
- **Primary Language**: Unknown
- **License**: EPL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 考试出卷系统（网络版）

一个功能完善的**支持多用户联网访问**的考试出卷系统，支持题库管理、富文本图片题干、自动/手动组卷、基于 Word 模板的试卷导出、Excel 批量导入题库。同时支持 **Windows** 与 **麒麟（Kylin，含 ARM64）** 桌面操作系统，可部署在一台服务器上供局域网内多台电脑同时使用。

> 本仓库为**公开仓库**，部署到生产环境前请务必修改默认管理员口令与 `SECRET_KEY`（见文末「安全提示」）。

---

## 一、功能特性

- **题库管理**：四种题型（单选 / 多选 / 判断 / 问答），两级分类（一级 + 二级），1–5 难度评级，答案解析，按分类 / 题型 / 关键词筛选。
- **富文本 + 图片题干**：题目内容与选项支持富文本编辑，图片以 base64 内嵌，不依赖外链、导出 Word 时一并带出。
- **自动 / 手动组卷**：按分类与题型设定题量与分值，随机抽题并支持试卷预览。
- **Word 模板导出**：试卷导出基于 Word 模板（`{{占位符}}` + 块标记），可导出「试题卷」与「答案卷」。
- **Excel 批量导入**：提供 Excel 模板，按列批量导入题目；答案格式自动归一（多选 `ABD` / `A,B,D` / `A B D` 均可，判断 `正确/错误` 兼容 `√/×`）。
- **多用户权限**：管理员 / 普通用户，用户增删改查，密码加密存储。
- **数据备份**：SQLite 文件库 `data/exam.db`，整体复制目录即可迁移；题库亦支持 JSON 导出。

---

## 二、技术栈

| 层 | 技术 |
|---|---|
| 后端 | Python 3.8+ + Flask 3.0 |
| 数据库 | SQLite（零配置、文件型） |
| 前端 | HTML + CSS + JavaScript（富文本编辑器为原生实现） |
| 文档 | python-docx（Word 导出）、openpyxl（Excel 导入） |

---

## 三、环境要求

- Python **3.8 及以上**（麒麟 ARM64 请使用系统自带 `python3`，或自行编译/安装对应架构版本）。
- 无需安装独立数据库服务（采用 SQLite 文件库，开箱即用）；通过局域网/内网即可多用户联网访问。

依赖见 `requirements.txt`：

```
Flask==3.0.0
python-docx==1.1.0
Werkzeug==3.0.1
openpyxl==3.1.2
```

---

## 四、快速开始

> 说明：系统默认监听 `0.0.0.0:5000`（见 `config.py` 的 `HOST` / `PORT`），即接受服务器所有网卡的连接，支持联网访问。本机浏览器访问 http://localhost:5000 ；同局域网其他电脑使用 http://<服务器IP>:5000 访问。若仅需本机访问，将 `HOST` 改回 `127.0.0.1` 即可。

### 方式一：Windows 一键启动（推荐）

直接双击 **`启动系统.bat`**，脚本会自动创建虚拟环境、安装依赖并启动，随后打开浏览器。

### 方式二：麒麟 / Linux 一键启动

```bash
# 1. 赋予执行权限（首次）
chmod +x 启动系统.sh

# 2. 运行启动脚本（自动建 venv、检测并补装依赖、启动、打开浏览器）
./启动系统.sh
```

如需把启动器放到桌面双击运行，执行：

```bash
./创建桌面快捷方式.sh     # 生成 .desktop 启动器并放到桌面
```

### 方式三：手动启动

```bash
# 1. 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动
python3 app.py                    # Windows: python app.py
```

### 默认账号

- 用户名：`admin`
- 密码：`admin123`

---

## 五、目录结构

```
exam/
├── app.py                 # 主应用（Flask 入口）
├── config.py             # 配置（HOST/PORT、SECRET_KEY、默认账号、题型）
├── database.py           # 数据库初始化
├── requirements.txt      # Python 依赖
├── 启动系统.bat          # Windows 一键启动
├── 启动系统.sh           # 麒麟/Linux 一键启动
├── 创建桌面快捷方式.sh    # 麒麟桌面 .desktop 启动器
├── import_questions.py   # 命令行批量导入 DOC/DOCX 题库
├── md2docx.py            # 操作说明书 Markdown→Word 转换脚本
├── services/             # 业务服务（docx_template / excel_import 等）
├── templates/            # HTML 模板
├── static/               # 静态资源（css / js，含富文本编辑器）
├── data/                 # 运行时数据（exam.db，已被 .gitignore 忽略）
├── 操作说明书.md / .docx  # 完整用户手册
├── 麒麟系统部署指南.md     # 麒麟部署详解
└── 网络版部署与运维指南.md # 多机联网部署、防火墙放行、备份与运维
```

---

## 六、使用流程（简）

1. **建分类**：分类管理 → 添加一级分类 → 在其下添加二级分类。
2. **录题**：题库管理 → 添加题目（可选富文本 + 图片）。
3. **组卷**：试卷管理 → 随机组卷 / 手动组卷，设题量与分值。
4. **导出**：试卷预览页 → 导出 Word（基于模板，含试题卷与答案卷）。

详细操作见 **`操作说明书.md`** / **`操作说明书.docx`**；麒麟部署见 **`麒麟系统部署指南.md`**；**多机联网部署、防火墙放行与运维见 `网络版部署与运维指南.md`**。

---

## 七、平台注意事项（麒麟 / 类 Unix）

1. **换行符（CRLF）**：仓库已通过 `.gitattributes` 将 `*.sh`、`*.py`、`*.js`、`*.css`、`*.html` 锁定为 **LF**。若从 Windows 拷贝文件到麒麟出现 `bash: ./启动系统.sh: /bin/bash^M: 解释器错误`，说明该文件被 Windows 转成了 CRLF，用 `sed -i 's/\r$//' 启动系统.sh` 修复后再运行。
2. **openpyxl 依赖**：`启动系统.sh` 会显式使用 `venv/bin/python` 并做「缺失检测式」安装（检测到缺 `openpyxl` 等会自动补装），避免 venv 创建早于依赖清单导致导入失败。
3. **GTK 告警（无害）**：麒麟 UKUI 桌面下启动报错 `failed to load module "ukuireload-gtk-module"` 是 GTK 主题热重载模块的无关告警，**不影响服务运行与浏览器打开**，可忽略；要彻底消除可注释 `~/.gtkrc-2.0` 中含 `ukuireload` 的行。
4. **ARM64**：麒麟 ARM64 平台请确认 `python3` 为 ARM64 架构版本，依赖（Flask / python-docx / openpyxl）均有对应 wheel，无需额外编译。

---

## 八、安全提示（公开仓库必读）

本仓库为**公开**，源码中 `config.py` 含以下默认值，克隆部署后请修改：

- `SECRET_KEY = 'exam-system-secret-key-2024'`
- 默认管理员口令 `admin123`（`DEFAULT_ADMIN_PASSWORD`）

建议改为从环境变量读取，或至少在首次部署后于「用户管理」中修改管理员密码。

> **网络版部署提示**：服务监听 `0.0.0.0`（所有网卡），请将其置于受信任的局域网/防火墙之后再对外开放；务必修改 `SECRET_KEY` 与默认管理员口令，避免未授权访问。

---

## 九、题库批量导入

- **Excel 导入**：题库管理页 → 「Excel 导入」→ 下载模板 → 按列填写（A~M 列）→ 上传。答案格式自动归一，分类不存在时自动创建，重复题目（同题型 + 同题干）自动跳过。
- **DOC/DOCX 导入**：命令行执行 `python3 import_questions.py <文件路径>`，支持旧版 `.doc`（OLE）与新版 `.docx`（python-docx）。

---

## 十、常见问题

**Q: 忘记管理员密码怎么办？**
A: 删除 `data/exam.db`，重启系统会自动重建默认管理员账号（注意：该操作会清空所有数据，请先备份）。

**Q: 如何迁移数据到另一台电脑？**
A: 直接复制整个 `exam` 目录（含 `data/`）即可；或先用题库 JSON 导出再导入。

**Q: 端口 5000 被占用？**
A: 修改 `config.py` 的 `PORT` 后重启。

**Q: SQLite 能存多少题？**
A: 百万级无压力，常规使用完全足够。

---

## 十一、技术支持

排查顺序：① Python 版本 ≥ 3.8；② 端口未被占用；③ 防火墙已放行 5000 端口（联网访问时需对其他电脑开放）；④ venv 依赖已完整安装（含 `openpyxl`、`waitress`）。