HUTBer - 智能刷题平台

基于积分经济的题库共享平台，用户上传试卷图片，AI自动识别题目并奖励积分

功能特性 • 界面预览 • 快速开始 • 架构设计 • API文档 • 部署指南

📖 目录

项目简介
界面预览
功能特性
技术栈
快速开始
详细使用说明
架构设计
数据库设计
API文档
配置说明
部署指南
安全与隐私
常见问题
开发指南
更新日志
许可证

🎯 项目简介

HUTBer 是一个基于 AI 的智能刷题平台，旨在帮助学生更高效地学习和复习。用户只需上传试卷图片，系统会自动识别题目并生成可刷题的题库。平台采用积分经济模型，鼓励用户分享资料，形成良性的学习社区。

核心理念

共享经济：上传资料获得积分，使用资料消耗积分
AI赋能：利用先进的视觉语言模型自动识别题目
隐私优先：支持匿名使用，无需强制注册
开源免费：完全开源，可自行部署

适用场景

📚 学生复习备考
👨‍🏫 教师题库管理
🏫 学校内部题库系统
📝 培训机构资料共享

🖼️ 界面预览

截图为演示数据（测试账号/本地环境），界面以实际部署为准。

题库广场	上传资料

个人中心	管理后台

✨ 功能特性

用户功能

1. 匿名使用

基于设备ID自动识别用户
无需注册即可使用基础功能
可选注册以同步数据

2. 双模式识别

VL模型模式（服务端）

使用 ModelScope Qwen VL 模型
识别准确率高
支持复杂排版
需要消耗 API 费用

浏览器OCR模式（客户端）

使用 Tesseract.js 在浏览器端识别
完全免费
隐私性更好
适合简单试卷

3. 智能去重

自动检测题目前30个字符
相同科目下匹配
重复题目仍保存但不奖励积分
防止刷分行为

4. 刷题模式

逐题答题，即时反馈
显示正确率统计
支持点击进度条跳题
答题进度自动保存
支持中途退出继续

5. 背题模式

直接显示答案
适合快速记忆
支持快速翻页

6. 大题支持

自动识别无选项的大题
提供 AI 参考答案
支持 DeepSeek API

7. 文档上传

支持图片格式：JPG、PNG、GIF、WebP
支持 DOCX 文档（自动转图片）
支持横向图片检测和旋转
最大文件大小：10MB

管理功能

1. 用户管理

查看所有用户列表
设置/取消管理员权限
重置用户密码
查看用户积分和上传记录

2. 内容审核

隐藏不当题目
查看题目详情
追溯上传者信息（IP、用户名）

3. 系统配置

热更新 API 配置
切换 OCR 识别模式
无需重启服务器

4. 原卷查看

仅管理员可查看原卷图片
防止版权风险

安全功能

1. 上传追踪

记录上传者 IP 地址
记录上传时的用户名快照
完整的时间戳记录
便于侵权追溯

2. 免责声明

首次访问自动弹出
用户必须同意才能使用
明确平台责任边界
提供侵权联系方式

3. 内容过滤

AI 自动审核上传内容
拒绝非试卷图片
科目匹配验证

🛠 技术栈

后端技术

技术	版本	用途
Go	1.21+	后端语言
Gin	1.9+	Web 框架
SQLite	3.x	数据库
GORM	-	ORM（可选）

前端技术

技术	版本	用途
HTML5	-	页面结构
Tailwind CSS	3.x	UI 样式
Vanilla JavaScript	ES6+	交互逻辑
Tesseract.js	5.x	浏览器 OCR
mammoth.js	1.6+	DOCX 解析
html2canvas	1.4+	HTML 转图片

AI 模型

模型	提供商	用途
qwen-vl-max-latest	ModelScope	图片识别和题目提取
DeepSeek	DeepSeek	文本解析和 AI 答案

🚀 快速开始

环境要求

Go 1.24 或更高版本
现代浏览器（Chrome、Firefox、Edge）
（可选）服务端 VL 识别配置：VL_ENDPOINT / VL_KEY / VL_MODEL
（可选）文本模型配置（大题 AI 参考答案等）：TEXT_ENDPOINT / TEXT_KEY / TEXT_MODEL

安装步骤

1. 克隆项目

git clone https://github.com/asts-top/hutber.git
cd hutber

2. 安装依赖

go mod tidy

3. 配置环境变量（可选）

默认 OCR_MODE=browser（浏览器端 OCR），无需任何模型 Key 即可体验上传/刷题。

可参考 .env.example，并通过环境变量注入配置：

# 服务端口（可选，默认 8080）
export PORT=8080

# OCR 模式：browser（默认）或 vl
export OCR_MODE=browser

# 管理员账号（可选；默认 admin/admin123）
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=admin123

# 服务端 VL 识别（OCR_MODE=vl 时需要）
# export VL_ENDPOINT=https://api.example.com/v1/chat/completions
# export VL_KEY=sk-your-api-key-here
# export VL_MODEL=qwen-vl-max-latest

# 文本模型（大题 AI 参考答案等功能需要）
# export TEXT_ENDPOINT=https://api.example.com/v1/chat/completions
# export TEXT_KEY=sk-your-api-key-here
# export TEXT_MODEL=deepseek-chat

4. 运行服务

go run main_debug.go

服务器将在 http://localhost:8080 启动。

5. 访问平台

打开浏览器访问：

主页：http://localhost:8080
管理后台：http://localhost:8080/frontend/admin-login.html

测试账号

类型	用户名	密码	积分	说明
普通用户	testuser	test123456	80	可上传和刷题
管理员	admin	admin123	-	完全权限
设备ID	device_demo_001	-	100	匿名用户

📚 详细使用说明

用户端使用流程

1. 首次访问

打开浏览器访问 http://localhost:8080
阅读并同意免责声明
系统自动分配设备ID，无需注册即可使用

2. 上传试卷

步骤：

点击主页的"上传资料"按钮
填写资料标题（如"高数期末试卷"）
选择科目（数学、物理、英语等）
上传文件（支持图片或DOCX）
等待AI识别（显示进度条）
识别完成后获得积分奖励

注意事项：

图片需清晰可见
横向试卷会自动检测并提示旋转
重复题目不会获得积分
上传者可免费查看自己上传的题目

3. 刷题练习

刷题模式：

在主页选择想要练习的资料
点击进入详情页
选择"刷题"模式
逐题答题，系统即时判断对错
查看正确率统计
可点击进度条跳转到任意题目
进度自动保存，随时可继续

背题模式：

切换到"背题"模式
直接显示答案和解析
适合快速记忆和复习

4. 查看AI答案

对于大题或没有答案的题目：

点击"获取AI答案"按钮
系统调用DeepSeek API生成参考答案
答案仅供参考，不保证完全正确

管理员使用流程

1. 登录管理后台

访问 http://localhost:8080/frontend/admin-login.html
使用管理员账号登录（admin / admin123）
进入管理后台

2. 用户管理

查看所有注册用户
设置/取消管理员权限
重置用户密码
查看用户积分和上传记录

3. 内容审核

隐藏不当题目
追溯上传者信息（IP、用户名）
查看题目详情

4. 系统配置

切换OCR识别模式（VL/浏览器）
更新API密钥
配置立即生效，无需重启

🏗 架构设计

系统架构

用户浏览器 (HTML/CSS/JS)
    ↓
Gin Web 框架 (Go)
    ↓
SQLite 数据库
    ↓
外部 API (ModelScope/DeepSeek)

核心模块

认证模块：设备ID + 用户名密码双模式
上传模块：VL识别 + 浏览器OCR双模式
题库模块：刷题、背题、AI答案
积分模块：上传奖励、查看扣费、去重检测
管理模块：用户管理、内容审核、系统配置

💾 数据库设计

核心表结构

users 表 - 用户表

字段	类型	说明
id	INTEGER	主键
device_id	TEXT	设备ID（匿名用户）
username	TEXT	用户名
password	TEXT	密码哈希
credits	INTEGER	积分余额
is_admin	INTEGER	是否管理员
created_at	DATETIME	注册时间

resources 表 - 资料表

字段	类型	说明
id	INTEGER	主键
title	TEXT	资料标题
subject	TEXT	科目
uploader_id	INTEGER	上传者ID
uploader_ip	TEXT	上传者IP地址
uploader_username	TEXT	上传时的用户名快照
file_data	TEXT	原卷图片Base64
file_type	TEXT	文件MIME类型
created_at	DATETIME	创建时间

questions 表 - 题目表

字段	类型	说明
id	INTEGER	主键
resource_id	INTEGER	所属资料ID
uploader_id	INTEGER	上传者ID
uploader_ip	TEXT	上传者IP地址
uploader_username	TEXT	上传时的用户名快照
subject	TEXT	科目
question_text	TEXT	题目内容
options	TEXT	选项（用\|分隔）
answer	INTEGER	答案索引
created_at	DATETIME	创建时间

📡 API文档

用户相关

POST /api/register

注册新用户

请求体：

{
  "username": "testuser",
  "password": "password123"
}

响应：

{
  "success": true,
  "token": "jwt-token-here",
  "user_id": 1,
  "credits": 50
}

POST /api/login

用户登录

请求体：

{
  "username": "testuser",
  "password": "password123"
}

响应：

{
  "success": true,
  "token": "jwt-token-here",
  "user_id": 1,
  "credits": 80
}

资料相关

GET /api/resources

获取资料列表

响应：

[
  {
    "id": 1,
    "title": "高数期末试卷",
    "subject": "数学",
    "question_count": 20,
    "uploader": "testuser",
    "view_count": 10
  }
]

POST /api/upload

上传资料（VL模式）

请求： multipart/form-data

title: 资料标题
subject: 科目
file: 图片文件

响应：

{
  "success": true,
  "question_count": 20,
  "new_count": 18,
  "dup_count": 2,
  "credits_earned": 180,
  "new_balance": 230
}

⚙️ 配置说明

环境变量

变量名	必需	默认值	说明
PORT	否	8080	服务端口
OCR_MODE	否	browser	OCR 模式：browser（浏览器端）/ vl（服务端 VL）
ADMIN_USERNAME	否	admin	管理员用户名
ADMIN_PASSWORD	否	admin123	管理员密码
VL_ENDPOINT	否	-	服务端 VL 模型端点（OCR_MODE=vl 时必需；也可在后台设置）
VL_KEY	否	-	服务端 VL 模型 Key（同上）
VL_MODEL	否	-	服务端 VL 模型名（同上）
TEXT_ENDPOINT	否	-	文本模型端点（AI 参考答案等功能需要；也可在后台设置）
TEXT_KEY	否	-	文本模型 Key
TEXT_MODEL	否	-	文本模型名

管理后台配置

可在管理后台动态配置以下项目：

VL模型端点、Key、模型名、返回格式（OpenAI/Gemini）
文本模型端点、Key、模型名
OCR识别模式（VL/浏览器）
配置立即生效，无需重启

🚢 部署指南

本地部署

# 1. 克隆项目
git clone https://github.com/asts-top/hutber.git
cd hutber

# 2. 安装依赖
go mod tidy

# 3. 配置环境变量（可选）
export OCR_MODE=browser
# 如需服务端识别，配置 VL_*；如需大题 AI 参考答案，配置 TEXT_*
# export VL_ENDPOINT=https://api.example.com/v1/chat/completions
# export VL_KEY=sk-xxx
# export VL_MODEL=qwen-vl-max-latest
# export TEXT_ENDPOINT=https://api.example.com/v1/chat/completions
# export TEXT_KEY=sk-xxx
# export TEXT_MODEL=deepseek-chat

# 4. 运行服务
go run main_debug.go

生产部署

# 1. 编译
go build -o hutber main_debug.go

# 2. 运行
./hutber

Docker 部署（推荐）

FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod tidy && go build -o hutber main_debug.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/hutber .
COPY --from=builder /app/frontend ./frontend
EXPOSE 8080
CMD ["./hutber"]

# 构建镜像
docker build -t hutber:latest .

# 运行容器
docker run -d -p 8080:8080 \
  -e OCR_MODE=browser \
  -v $(pwd)/snapquiz.db:/app/snapquiz.db \
  hutber:latest

🔒 安全与隐私

上传追踪机制

为防止侵权和滥用，系统记录：

上传者IP地址：用于追溯恶意上传来源
用户名快照：记录上传时的用户名（即使用户改名也能追溯）
上传时间：完整的时间戳记录

免责声明

首次访问时自动弹出免责声明
用户必须同意后才能使用平台
平台仅提供技术服务，不对上传内容负责
侵权联系邮箱：admin@hutber.top

内容审核

管理员可隐藏不当内容
支持题目级别的隐藏
原卷查看功能仅对管理员开放
AI自动审核上传内容

数据安全

密码使用bcrypt加密存储
JWT Token认证
SQL注入防护
XSS攻击防护

❓ 常见问题

Q1: 为什么上传后没有获得积分？

A: 可能是以下原因：

题目与数据库中已有题目重复（前30字符相同）
AI识别失败或未识别到有效题目
图片不清晰或不是试卷

Q2: 如何切换OCR识别模式？

A: 管理员可在管理后台的"识别模式"设置中切换：

VL模型：准确但需要API费用
浏览器OCR：免费但准确率较低

Q3: 上传的原卷图片会被公开吗？

A: 不会。原卷图片仅管理员可查看，普通用户和上传者都无法查看。

Q4: 如何获取ModelScope API Key？

A: 访问 https://www.modelscope.cn/ 注册账号并申请API密钥。

Q5: 数据库文件在哪里？

A: 数据库文件为 snapquiz.db，位于项目根目录。

Q6: 如何备份数据？

A: 直接复制 snapquiz.db 文件即可完成备份。

Q7: 支持哪些图片格式？

A: 支持 JPG、PNG、GIF、WebP 格式，以及 DOCX 文档（自动转图片）。

Q8: 横向试卷如何处理？

A: 系统会自动检测横向图片并提示用户旋转，用户可使用预览功能手动旋转。

👨‍💻 开发指南

项目结构

hutber/
├── main_debug.go          # 主程序入口
├── snapquiz.db            # SQLite数据库
├── go.mod                 # Go依赖管理
├── go.sum                 # 依赖校验
├── README.md              # 项目文档
└── frontend/              # 前端文件
    ├── new-index.html     # 主页（题库广场）
    ├── detail.html        # 资料详情（刷题/背题）
    ├── new-login.html     # 登录/注册页
    ├── admin.html         # 管理后台
    └── admin-login.html   # 管理员登录页

开发环境搭建

# 1. 安装Go 1.21+
# 2. 克隆项目
git clone https://github.com/asts-top/hutber.git
cd hutber

# 3. 安装依赖
go mod tidy

# 4. 运行开发服务器
go run main_debug.go

代码规范

使用 gofmt 格式化代码
遵循 Go 官方代码规范
添加必要的注释
编写单元测试

贡献指南

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📝 更新日志

v1.0.0 (2026-01-19)

新增功能

✅ 双模式识别（VL模型 + 浏览器OCR）
✅ 智能去重检测
✅ 答题进度保存
✅ 点击进度条跳题
✅ 大题AI答案支持
✅ 上传者免费查看自己的题目
✅ 横向图片检测和旋转
✅ DOCX文档支持
✅ 上传追踪（IP + 用户名）
✅ 免责声明弹窗
✅ 管理后台热更新配置

安全改进

✅ 记录上传者IP地址
✅ 记录用户名快照
✅ 原卷仅管理员可见
✅ 免责声明机制

优化改进

✅ OCR错误自动修正
✅ 上传进度条显示
✅ 品牌更新（SnapQuiz → HUTBer）
✅ 红色主题UI

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

Gin - Web 框架
ModelScope - VL 模型服务
DeepSeek - AI 文本服务
Tesseract.js - 浏览器 OCR
Tailwind CSS - UI 框架

📧 联系方式

项目主页：https://github.com/asts-top/hutber
问题反馈：https://github.com/asts-top/hutber/issues
侵权联系：admin@hutber.top

⭐ 如果这个项目对你有帮助，请给个 Star！

Made with ❤️ by HUTBer Team

Name		Name	Last commit message	Last commit date
docs/screenshots		docs/screenshots
frontend		frontend
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
OPEN_SOURCE_CHECKLIST.md		OPEN_SOURCE_CHECKLIST.md
README.md		README.md
debug_server.go		debug_server.go
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_debug.go		main_debug.go
main_demo.go		main_demo.go
main_old.go		main_old.go
schema.sql		schema.sql
schema_new.sql		schema_new.sql
test.jpg		test.jpg
test2.jpg		test2.jpg
test_api.sh		test_api.sh
test_client.go		test_client.go
test_demo.go		test_demo.go

Latest commit

History

Folders and files

Repository files navigation

HUTBer - 智能刷题平台

📖 目录

🎯 项目简介

核心理念

适用场景

🖼️ 界面预览

✨ 功能特性

用户功能

1. 匿名使用

2. 双模式识别

3. 智能去重

4. 刷题模式

5. 背题模式

6. 大题支持

7. 文档上传

管理功能

1. 用户管理

2. 内容审核

3. 系统配置

4. 原卷查看

安全功能

1. 上传追踪

2. 免责声明

3. 内容过滤

🛠 技术栈

后端技术

前端技术

AI 模型

🚀 快速开始

环境要求

安装步骤

1. 克隆项目

2. 安装依赖

3. 配置环境变量（可选）

4. 运行服务

5. 访问平台

测试账号

📚 详细使用说明

用户端使用流程

1. 首次访问

2. 上传试卷

3. 刷题练习

4. 查看AI答案

管理员使用流程

1. 登录管理后台

2. 用户管理

3. 内容审核

4. 系统配置

🏗 架构设计

系统架构

核心模块

💾 数据库设计

核心表结构

users 表 - 用户表

resources 表 - 资料表

questions 表 - 题目表

📡 API文档

用户相关

POST /api/register

POST /api/login

资料相关

GET /api/resources

POST /api/upload

⚙️ 配置说明

环境变量

管理后台配置

🚢 部署指南

本地部署

生产部署

Docker 部署（推荐）

🔒 安全与隐私

上传追踪机制

免责声明

内容审核

数据安全

❓ 常见问题