lch收发助手 · 开发与使用文档

1文档与产品说明

1.1 这是什么

lch收发助手是一套面向机房、教室、办公室等内部网络场景的 文件共享 + 打字练习 + 打字游戏平台。它由两部分组成:

典型使用场景:机房、教室、办公室、实训室。

1.2 软件的开放范围 重要

1.3 版本说明

本软件的不同位置可能显示 1.2.0、1.2.1、1.2.2 等版本号,这是历史迭代留下的显示差异, 不影响功能使用;对外统一以 v1.2.0 作为发行版本标识。游戏开发接口请始终以本文档(最新版)为准。

1.4 文档导航

2功能特性

3快速上手

本章面向部署者(通常是老师或管理员)。本软件以打包好的程序形式分发,目标电脑无需安装开发环境。

3.1 启动服务端

按分发形式二选一:

复制A. 启动器版:双击程序目录中的「启动器」→ 点「启动服务」
B. EXE 版  :双击「lch收发助手.exe」→ 在窗口里点「启动服务」

启动成功后会显示访问地址与初始管理员信息:

复制地址   : http://<本机IP>:8080/
后台   : http://<本机IP>:8080/admin/login
管理员 : admin / admin123  (初始默认密码)
⚠️  首次登录后必须修改密码，改完此密码不再显示

3.2 默认账号与首次登录

3.3 端口与防火墙

• 默认端口 8080;若被占用,在启动器里改端口后重启即可。
• 改端口后,所有学生使用的地址与客户端的端口配置都要同步更新,否则会连不上。
• 需要放行 Windows 防火墙的对应端口,否则同一局域网的其他电脑打不开网页:

  复制netsh advfirewall firewall add rule name="lch" dir=in action=allow protocol=TCP localport=8080

3.4 数据与备份

• 程序目录下的数据文件夹在首次运行时自动生成,存放账号、文件索引、成绩与运行配置。
• 共享的文件本体存放在文件目录中,同样在首次运行时自动创建。
• 备份建议:定期整体备份数据文件夹与文件目录即可;恢复时保持目录结构不变,整个程序目录一起替换。

3.5 部署检查清单

• ✅ 整个程序文件夹一起拷贝,不要只复制其中单个可执行文件(会缺少运行库导致启动失败)。
• ✅ 防火墙已放行服务端口。
• ✅ 已把杀毒软件对该程序目录设为信任(未签名的打包程序容易被误报)。
• ✅ 已修改超级管理员默认密码。
• ✅ 组网使用的默认密码已改为自定义强密码(见第 7 章)。
• ✅ 已确认学生机器能打开服务端地址。

4学生使用手册

4.1 首次使用(注册)

1. 用浏览器打开老师提供的地址(形如 http://10.126.126.1:8080/);或打开客户端程序点「开始连接」。
2. 点击页面上的登录按钮,切换到「注册」页签。
3. 填写:姓名(即账号)、密码、再次确认密码、图片验证码。
4. 提交后自动登录,可以开始使用。

4.2 上传文件

1. 进入「上传」页面。
2. 把文件拖入虚线区域,或点击按钮选择文件;也可以选择整个文件夹(会保留文件夹结构)。
3. 在列表中确认上传内容,移除不需要的;重复选择的文件会自动跳过。
4. 点击开始上传,进度条会显示百分比、速度与预计剩余时间。

4.3 下载文件

• 首页就是文件列表,点条目即可下载;下载不需要登录。
• 列表显示文件类型图标、大小与上传者。
• 自己上传的文件旁有删除按钮,可以随时删除(配额同时释放);别人的文件无权删除。
• 使用客户端时,点下载会弹出保存对话框(默认存到系统「下载」文件夹),并在左侧下载管理面板显示进度。

4.4 打字练习

1. 进入「打字」页面,选择素材:下拉框中的平台模板,或点击按钮选择自己电脑上的代码/文本文件。
2. 按需切换「要打注释 / 不打注释」、「显示键盘 / 隐藏键盘」;空行与行首缩进会自动跳过。
3. 照屏幕文本输入,跟着高亮键盘与手指提示操作。
4. 顶部实时显示:用时、速度(字符/分钟)、正确率、输错率。
5. 完成后在弹出的成绩框中确认提交,成绩进入系统,老师可以查看。

4.5 打字游戏

• 进入「游戏」页面,选择游戏卡片进入。
• 联机游戏输入相同的房间号即可与同学同场竞技;房间可能有人数上限。
• 成绩自动记录,可在游戏内查看,也可由老师在后台查看。

4.6 切换皮肤

点击页面右上角的 🎨 图标,选择:经典 / 卡通 / 云母 / 暗黑 / 赛博 / 森林。选择会被浏览器记住,下次访问自动生效。

5管理员手册

5.1 登录与改密

1. 访问服务端地址 + /admin/login。
2. 用 admin / admin123 登录(需填验证码)。
3. 系统强制要求修改密码(至少 6 位、两次一致),改完即可进入后台。

5.2 后台功能地图

5.3 常用运维动作

新增一个游戏

1. 把游戏插件文件夹放入平台的游戏目录(开发方法见第 8 章)。
2. 在后台「游戏管理」点「重新扫描」,或重启服务端。
3. 确认该游戏处于「启用」状态,学生端即可看到。

调整上传限制

• 在「设置」中修改被禁止的文件扩展名列表;填写后完全覆盖系统默认值,清空则恢复为默认的 46 类。
• 注意:清空黑名单等于放开所有类型,包括可执行文件,请谨慎操作。

限制网速

• 在「设置」中分别填写上传与下载限速值,单位 KB/s;填 0 表示不限速。
• 限速对大文件传输效果明显,可用于保证多人同时使用时的网络质量。

重置学生密码

• 在「学生管理」中找到该学生并执行重置,新密码至少 4 位,然后告知学生。
• 学生本人无法自行找回密码。

查看哪些学生机在线

• 客户端会定期上报设备信息。管理端可看到设备的主机名、使用者、系统版本与首次/最近在线时间。
• 上报的运行日志同样由管理端接收,可用于排查学生机问题。

下发客户端更新

• 把新的客户端目录替换到服务端的客户端分发目录,并同步更新目标版本号。
• 客户端下次连接时会自动比对文件并静默更新,学生通常无需操作。
• 客户端版本号与更新公告的设置入口请咨询软件维护者(不同发行版的界面可能略有差异)。

5.4 安全提醒

1. 首次部署后立即修改超级管理员默认密码。
2. 把组网默认密码改成自定义强密码(见第 7 章)。
3. 不要把服务端直接暴露到公网——本产品面向内部网络设计。
4. 文件类型黑名单只按扩展名拦截,不能替代杀毒软件。
5. 定期备份数据文件夹与文件目录。

6客户端使用说明

客户端用于学生机与服务端不在同一局域网时自动完成组网并打开服务端页面,同时提供本地下载管理与自动更新。

6.1 界面构成

6.2 使用流程

1. 把老师发来的客户端文件夹与配置文件放在同一个目录下。
2. 双击运行客户端,首次需同意「用户协议」(要滚动到底部才能点同意;不同意则退出程序)。
3. 点「开始连接」,程序会自动组网并搜索服务端;自动搜索最长约需 45 秒,请耐心等待。
4. 连接成功后右侧会自动载入服务端页面,像用浏览器一样上传、下载、打字、玩游戏。
5. 在网页里点击下载时,会弹出保存对话框,并在左侧面板显示下载进度。

6.3 行为特性

6.4 客户端常见故障

7网络与组网

7.1 两种接入方式

7.2 概念说明

7.3 管理员的组网操作

1. 在启动器上点「外网组网」,打开组网窗口。
2. 填写四项:网络名(默认 lch-share)、网络密码(默认值必须改掉,建议 8 位以上)、 本机虚拟 IP(默认 10.126.126.1)、中转节点(形如 tcp://域名:端口)。
3. 启动组网。窗口底部会显示服务端公钥指纹,供学生核对。
4. 组网成功后,启动器会自动导出客户端配置文件。把该配置文件与客户端文件夹一起发给学生即可。

7.4 连接不通的排查顺序

1. 先看服务端:本机能打开网页吗?不能 → 服务未启动或端口被占用。
2. 再看网络:其他电脑能访问服务器吗?不能 → 检查是否同一网段,或客户端是否已成功组网。
3. 再看防火墙:服务器是否放行了该端口?
4. 再看地址:是否误把地址写成 127.0.0.1?那是本机地址,别的电脑连不上。
5. 最后看配置一致性:服务端与客户端的网络名、网络密码、中继节点、端口是否完全一致。

8游戏开发指南 开放接口

这是本软件唯一对外开放的扩展点。任何人都可以按本章规范开发游戏插件,放入游戏目录后由平台加载运行。 本章只描述插件如何开发,不涉及平台自身的内部实现。

8.1 开放范围与开发者守则

8.2 插件目录结构

把该文件夹整体放入平台的游戏目录,然后在后台点「重新扫描」或重启服务端即被加载。 目录名以 _ 开头的文件夹会被平台跳过,可用于存放草稿。

8.3 元数据 game.json

复制{
  "key": "my_game",
  "name": "我的游戏",
  "icon": "🎲",
  "description": "一句话说明玩法",
  "author": "你的名字",
  "version": "1.0",
  "has_server": true,
  "min_players": 1,
  "max_players": 8
}

8.4 服务端类接口(server.py)

在 server.py 中定义一个名为 Game 的类,继承平台提供的基类 BaseGame,并实现两个可选方法:

复制from games.base import BaseGame


class Game(BaseGame):

    def register_routes(self, bp):
        """注册自定义 HTTP 接口。
        平台已为你的插件准备好带前缀的路由对象 bp，
        在这里用 @bp.route 注册，最终地址为 /api/game/<你的key>/<你的路径>。
        """

    def register_socketio(self, socketio, namespace):
        """注册实时通信事件（联机游戏用）。
        namespace 已固定为 /game/<你的key>，
        在这里用 @socketio.on("事件名", namespace=namespace) 注册。
        """

基类在实例化时已经为插件准备好以下属性,直接使用即可:

8.5 平台通路约定

8.6 提交成绩(当前做法 + SDK 建议)

成绩提交是插件与平台之间唯一的「数据写入」通路。平台上的成绩分两类:

当前做法(示例):插件在服务端把成绩记录写入平台的成绩表,并调用平台日志以便管理员看到:

复制# server.py 内，收到前端提交后
from datetime import datetime
from db import execute
from logger import log_game_score

def save_score(game_key, student_name, score, detail=""):
    execute(
        "INSERT INTO game_scores(game_key, student_name, score, detail, created_at) "
        "VALUES(?,?,?,?,?)",
        (game_key, student_name, int(score), detail,
         datetime.now().isoformat(timespec="seconds")),
    )
    log_game_score(game_key, student_name, score)

8.7 前端页面约定(static/index.html)

• 你的页面会被平台以 iframe 载入,所以不需要自己写导航栏、登录框等平台级界面。
• 页面尺寸自适应 iframe 即可;建议同时适配浅色与深色皮肤下的可读性(平台支持 6 套皮肤)。
• 获取学生姓名:平台会在父页面渲染一个显示当前登录学生的元素(#studentWelcome),插件可通过 parent.document.getElementById("studentWelcome") 读取其文本;取不到时请给出兜底名称。
• 实时通信:使用平台提供的实时通信客户端库,连接到你自己的命名空间:

  复制const socket = io("/game/你的key");
  socket.on("connect", () => { socket.emit("join", { name: 学生姓名 }); });
  socket.on("你的自定义事件", (data) => { /* 处理 */ });

• 建议通过 postMessage 或平台既有的下载入口处理文件下载,不要直接操作父页面。

8.8 最小可运行示例

三个文件即可跑通一个联机游戏(房间 + 实时分数 + 成绩入库):

复制// ① game.json
{
  "key": "my_game",
  "name": "我的游戏",
  "icon": "🎲",
  "description": "最小联机示例",
  "author": "你",
  "version": "1.0",
  "has_server": true,
  "min_players": 1,
  "max_players": 8
}

复制# ② server.py
from flask import request, jsonify
from games.base import BaseGame

ROOMS = {}


class Game(BaseGame):

    def register_routes(self, bp):
        # 最终地址：GET /api/game/my_game/hello
        @bp.route("/hello")
        def hello():
            return jsonify(ok=True, msg=f"来自 {self.name} 的问候")

    def register_socketio(self, socketio, namespace):

        def broadcast(room_id):
            room = ROOMS.get(room_id)
            if not room:
                return
            socketio.emit("room_update", {
                "room_id": room_id,
                "players": [{"name": p["name"], "score": p["score"]}
                            for p in room["players"].values()],
            }, namespace=namespace, room=room_id)

        @socketio.on("join", namespace=namespace)
        def on_join(data):
            sid = request.sid
            room_id = str(data.get("room_id") or "default")[:32]
            name = str(data.get("name") or "同学")[:16]
            room = ROOMS.setdefault(room_id, {"players": {}})
            if len(room["players"]) >= self.max_players:
                socketio.emit("error_msg", {"msg": "房间已满"}, to=sid, namespace=namespace)
                return
            room["players"][sid] = {"name": name, "score": 0}
            socketio.server.enter_room(sid, room_id, namespace=namespace)
            broadcast(room_id)

        @socketio.on("add_score", namespace=namespace)
        def on_add_score(data):
            sid = request.sid
            for room_id, room in ROOMS.items():
                if sid in room["players"]:
                    room["players"][sid]["score"] += int(data.get("delta", 1))
                    broadcast(room_id)
                    break

        @socketio.on("submit_score", namespace=namespace)
        def on_submit():
            sid = request.sid
            for room_id, room in ROOMS.items():
                if sid in room["players"]:
                    p = room["players"][sid]
                    save_score(self.key, p["name"], p["score"], f"room={room_id}")
                    socketio.emit("score_saved", {"score": p["score"]},
                                  to=sid, namespace=namespace)
                    break

        @socketio.on("disconnect", namespace=namespace)
        def on_disconnect():
            sid = request.sid
            for room_id, room in list(ROOMS.items()):
                if sid in room["players"]:
                    del room["players"][sid]
                    if room["players"]:
                        broadcast(room_id)
                    else:
                        ROOMS.pop(room_id, None)
                    break


# save_score 见 8.6 节
def save_score(game_key, student_name, score, detail=""):
    from datetime import datetime
    from db import execute
    from logger import log_game_score
    execute(
        "INSERT INTO game_scores(game_key, student_name, score, detail, created_at) "
        "VALUES(?,?,?,?,?)",
        (game_key, student_name, int(score), detail,
         datetime.now().isoformat(timespec="seconds")),
    )
    log_game_score(game_key, student_name, score)

复制<!-- ③ static/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>我的游戏</title>
  <style>
    body{font-family:system-ui,"Microsoft YaHei",sans-serif;margin:0;padding:20px}
    button{padding:8px 18px;border-radius:10px;border:1px solid #ccd;cursor:pointer}
    #players{margin-top:14px;line-height:1.9}
  </style>
</head>
<body>
  <h2>🎲 我的游戏</h2>
  <button id="addScore">加分 +1</button>
  <button id="submit">提交成绩</button>
  <div id="players">等待加入…</div>

  <script src="/socket.io/socket.io.js"></script>
  <script>
    // 从父页面读取当前登录学生姓名（取不到时兜底）
    var el = parent.document.getElementById("studentWelcome");
    var myName = el && el.textContent.trim() ? el.textContent.trim() : "同学";

    var socket = io("/game/my_game");
    socket.on("connect", function () {
      socket.emit("join", { room_id: "default", name: myName });
    });
    socket.on("room_update", function (d) {
      document.getElementById("players").innerHTML =
        d.players.map(function (p) { return p.name + " : " + p.score; }).join("<br>");
    });
    socket.on("score_saved", function (d) { alert("成绩已提交：" + d.score); });
    socket.on("error_msg", function (d) { alert(d.msg); });

    document.getElementById("addScore").onclick = function () {
      socket.emit("add_score", { delta: 1 });
    };
    document.getElementById("submit").onclick = function () {
      socket.emit("submit_score", {});
    };
  </script>
</body>
</html>

8.9 内置示例游戏的事件设计参考

平台自带两个示例插件,可直接作为命名与流程设计参考(目录名与事件名如下):

8.10 加载与调试

1. 把插件文件夹放入游戏目录,后台点「重新扫描」,或重启服务端。
2. 在后台「游戏管理」确认插件已被识别(game.json 解析失败、目录名以 _ 开头都会导致跳过)。
3. 确认游戏处于启用状态,再到学生端游戏列表查看。
4. 服务端控制台会输出插件加载相关的提示信息,加载或注册失败时可据此定位。

8.11 发布插件的建议

• 目录名、key、事件名统一使用英文小写加下划线,避免中文与空格带来的兼容问题。
• 插件内自带说明文件(玩法、操作键位、作者联系方式),便于管理员与学生理解。
• 只使用本章公开的接口;不要依赖未经公开的内部结构,以免平台升级后失效。
• 若插件需要额外的 Python 依赖,请在说明中明确提出,由维护者安装后再启用。

9常见问题

10安全注意事项

10.1 部署方必做

10.2 使用方的边界认知

• 文件类型黑名单只按扩展名判断,改名的可执行文件仍可能通过,不能替代杀毒软件。
• 下载不需要登录,能打开页面的人都能下载文件;若文件敏感,请勿上传。
• 账号跟人不跟机器,请勿共用账号,以免成绩与文件归属混乱。
• 插件开发者请遵守第 8.1 节的守则:不触碰平台内部数据与文件,不绕过登录鉴权。

10.3 漏洞与问题反馈

发现安全问题或程序缺陷,请联系维护者:📧 [email protected]。 反馈客户端问题时,请一并提供「上报日志」生成的内容,可显著加快定位速度。

11附录

11.1 术语表

11.2 关键参数速查

11.3 文档范围声明

11.4 版本与联系方式