故障排除

软件出问题别慌, 按"看现象 → 查日志 → 联系作者"三步走, 九成问题十分钟内能自己搞定。

排查思路: 先看现象, 再查日志, 最后联系作者

遇到任何问题, 不要急着重装, 也不要急着删数据。按下面的顺序来, 大部分情况自己就能处理。

1. 看现象是软件打不开, 还是打开了但某个功能用不了? 把现象记清楚, 比如"点登录按钮转圈半分钟没反应"。
2. 查日志用 admin 账号登录, 进左侧菜单"操作日志", 看最近一条红色的报错; 如果根本进不去系统, 看本机 D:\乡村管理系统\logs\(没 D 盘则在 C:\Users\你的用户名\AppData\Roaming\cn.village.admin\logs\) 下最新的 .log 文件, 拉到最后几行。
3. 试基础三招关掉软件重开一次, 不行就重启电脑, 还不行就换个浏览器(局域网访问时)。
4. 联系作者实在搞不定, 按本页最后一节"收集诊断信息"那一节把版本号+日志末尾 50 行发过来。

现象 1: 双击图标后没反应

双击桌面图标, 鼠标转一下沙漏就没动静了, 任务栏也没出现窗口。常见三种原因:

1. 软件已经在后台跑着了按 Ctrl + Shift + Esc 打开任务管理器, 看进程列表里有没有"乡村管理系统"或者 app.exe。有的话右键"结束任务", 再双击启动。
2. 被杀毒软件拦了看右下角通知栏有没有红色盾牌图标弹窗, 360 / 火绒 / Defender 都可能拦截 Tauri 打包的 exe。处理办法见下面"现象 12"。
3. 安装路径有中文或空格异常程序默认装在 D:\乡村管理系统\(D 盘不存在则回落 C:\Program Files\乡村管理系统\); 如果你手动改装到 D:\新建文件夹\ 这种带空格的路径下, 卸了重装回默认目录。

现象 2: 启动报错"端口 8848 被占用"

这表示电脑上已经有别的程序占了 8848 端口, 通常是上次的软件没退干净。

1. 先杀进程按 Win + R, 输入 cmd 回车, 在黑窗口里敲 netstat -ano | findstr 8848, 看最后一列那个数字(PID), 然后 taskkill /F /PID 那个数字。
2. 检查是不是装了两份比如同时装在了 D 盘和 C 盘, 或者上次卸载没卸干净又重装了一次。把多余的一份卸载掉。
3. 实在不行重启电脑这招永远有效, 别嫌土。

现象 3: 启动报错"无法访问数据库" / database is locked

SQLite 同一时刻只让一个写入者, 报这个错说明数据库被锁了。

1. 关掉所有相关窗口包括浏览器里别人在局域网访问的页面, 还有任务管理器里残留的进程。
2. 检查 .db 文件是不是被占用到 D:\乡村管理系统\data\(没 D 盘则在 %APPDATA%\cn.village.admin\data\) 文件夹, 如果有 data.db-journal 或 data.db-wal 但软件没在跑, 等 30 秒让系统自己释放; 还在就重启电脑。
3. 磁盘满了也会锁库看 C 盘和软件所在盘剩余空间, 少于 1GB 就清理一下临时文件。

现象 4: 登录提示"账号或密码错误"(但你确定没记错)

先确认三件事:

普通用户忘密码, admin 进"用户管理"点该用户那行的"重置密码"按钮, 手动填一个新密码(至少 6 位), 该用户下次登录时系统会强制要求改密。

如果是所有管理员账号都忘了密码, 系统本身不联网、没有"找回密码"邮件, 但留了一个本机应急口子, 登录页"忘记密码?"链接里也有同样的说明:

1. 关闭软件包含任务栏托盘里的后台进程, 一定要完全退出。
2. 打开数据目录默认在 D:\乡村管理系统\data\(没 D 盘则在 %APPDATA%\cn.village.admin\data\); 如果之前登录过"备份恢复"页面, 顶部"数据存储位置"显示的就是当前的准确路径。
3. 在数据目录顶层新建一个空文件, 命名为 RESET-ADMIN-PASSWORD右键新建文本文档, 改名时把 .txt 去掉也行, 带不带后缀都能识别。
4. 重新打开软件启动时系统会检测到这个标记文件, 把所有角色为管理员的账号密码统一重置为临时密码 reset123, 并删掉标记文件(不会重复触发)。
5. 用你的管理员账号名(默认账号是 admin, 如果改过用户名用改过的)+ 密码 reset123 登录系统会强制要求立即设置新密码, 设完这个应急口子就关闭了。

现象 5: 录入数据后保存按钮转圈不结束

转圈超过 10 秒还没结束, 大概率是某个字段触发了校验失败但提示没弹出来。

1. 先别关窗口关了就白填了。先看页面顶部有没有红色错误提示, 没有的话把可疑字段(身份证号、手机号、必填项)重新填一遍。
2. 重点检查必填字段和身份证号身份证字段会做 18 位校验, 输错一位就卡住。
3. 看关联字段如果这条记录关联到另一个模块(比如"低保户"关联"村民"), 关联目标必须先存在, 否则保存不进去。
4. 再试一次把可疑字段重新填一遍, 再点保存。还不行就复制内容到记事本, 关窗口重开。

现象 6: 局域网其他电脑访问不了

主机装了软件, 别的电脑浏览器打开 http://主机IP:8848 转圈或者直接报错。按这个顺序排:

1. 先确认开了"账号密码登录"这是最常见的原因: 默认的单机/免登录模式下, 软件只监听本机(127.0.0.1), 局域网电脑物理上就连不进来, 跟防火墙没关系。进主机的"系统设置 → 登录方式", 把"启用账号密码登录"打开。
2. 开关打开后要重启一次软件完全退出(包括托盘图标退出), 再重新打开。这个开关只在启动时生效, 开着的时候切换不会立刻让局域网连进来。
3. 打开开关时会自动弹一次防火墙授权系统会弹出 Windows 管理员授权窗口, 点"是"就自动放行了 8848 端口, 不需要再手动配置; 如果点了"取消"或者根本没弹出来, 才需要手动打开"Windows Defender 防火墙 → 高级设置 → 入站规则 → 新建规则", 选"端口", 输 8848, 允许连接。
4. 主机和客户端在同一个网段主机按 Win + R 输 cmd, 敲 ipconfig, 看 IPv4 地址(例如 192.168.1.20); 客户端的 IP 必须是 192.168.1.* 同前三段。
5. 主机不能断网, 也不能睡眠进"控制面板 → 电源选项", 把"睡眠"改成"从不"。
6. 客户端用主机 IP 不是 localhost客户端浏览器地址栏一定是主机 IP, 不是 127.0.0.1。

现象 7: 手机扫码后页面打不开

扫码填写 / 扫码上传生成的二维码, 村民手机扫了打不开:

现象 8: 导入卡在最后 1% 不动

Excel 导入到 99% 不动了, 不要关窗口, 它大概率还在跑。

1. 等 2 分钟最后 1% 一般是在写日志和建索引, 数据量大(超过 5000 行)时确实慢。
2. 检查匹配字段有没有重复用"增量"或"全量"策略时, 如果选的匹配字段(比如身份证号)在你的 Excel 里有重复行, 系统会反复对比, 卡很久。先在 Excel 里去重再导。
3. 还卡就关掉窗口关闭后重新进模块, 列表里如果已经看到大部分数据了, 说明事务还没提交完。等 5 分钟刷新页面。
4. 分批导下次单次别超过 3000 行, 拆开导更稳。

现象 9: 证明生成后乱码 / 不识别占位符

上传 docx 模板, 生成出来全是乱码或者 {{姓名}} 没被替换:

1. 占位符必须是英文大括号是 {{姓名}}, 不是 『姓名』 也不是中文大括号 ｛｛姓名｝｝。
2. 占位符不能被 Word 的拼写检查拆开在 Word 里如果你看到 {{姓 名}} 中间有红色波浪线, 多半是格式被切了。删掉重新输入一遍, 全程用同一种字体。
3. 字段名要和模块字段完全一致模块里字段叫"身份证号", docx 里就必须写 {{身份证号}}, 写成 {{身份证}} 不认。
4. 重新上传模板进"证明开具"页面, 点该模板的"编辑模板"图标换一份新文件, 或者先删掉旧的再点右上角"新建模板"重新上传, 让系统重新扫描占位符。

现象 10: 备份还原后数据不一致

从 .db 备份还原后, 感觉少了几条记录或者菜单变了。这是正常现象 - 备份是某一时刻的快照, 还原就回到那一刻。

1. 核对备份时间到"备份恢复"看你还原的那个备份是哪天几点的, 那之后录入的数据就不在里面。
2. 找回收站"全局回收站"里 7 天内删除的记录都还能还原。
3. 不要来回切换备份每次还原都会覆盖当前库, 来回切只会越来越乱。确认一份用就一直用。

现象 11: 软件越用越慢

用了大半年后翻页变慢、搜索变卡, 一般是这几个原因:

现象 12: Windows Defender 拦截 / 误报病毒

Tauri 打包的小众软件没花钱买证书, 被 Defender 误报很常见。完全不是病毒, 你可以放心加白。

1. 打开 Windows 安全中心开始菜单搜"Windows 安全中心" → "病毒和威胁防护"。
2. 找到隔离的文件点"保护历史记录", 找到被拦的 app.exe 或安装包。
3. 选"还原"并加入排除右键该文件, 选"允许"; 然后进"管理设置 → 排除项 → 添加排除项", 把整个安装目录加进去。
4. 360 / 火绒同理在它们的隔离区把文件恢复, 加入信任名单。

收集诊断信息(版本号 / 日志 / 系统信息)给作者

自己搞不定要联系作者, 请一次性把下面三样发过来, 别挤牙膏:

1. 版本号软件里没有直接显示版本号的页面, 去"控制面板 → 程序 → 程序和功能", 找到"乡村管理系统"这一行, 后面括号里的数字就是版本号; 或者到安装目录找到 app.exe, 右键"属性 → 详细信息", 看"文件版本"。
2. 日志末尾到 D:\乡村管理系统\logs\(没 D 盘则在 C:\Users\你的用户名\AppData\Roaming\cn.village.admin\logs\), 把最新的那个 .log 文件直接发过来; 如果太大, 用记事本打开拉到最后, 复制最后 100 行。
3. 系统信息按 Win + R 输 winver 截个图(Windows 版本); 顺便说一下电脑是台式机还是笔记本, 内存多大。
4. 说清现象"什么时候开始的"、"做了什么操作之后出现的"、"是偶尔还是每次都这样"。

紧急情况: 数据找不到了 - 别慌, 备份+回收站两道防线

看到列表空了一片、菜单不见了、记录消失了, 先深呼吸。这个系统有两道防线, 你的数据极大概率没真丢。

1. 第一道: 全局回收站左侧菜单"全局回收站", 切换到对应模块, 把误删的记录勾上点"还原"。7 天内删的都在。
2. 第二道: 自动备份软件每天第一次启动或每小时检查一次, 当天还没有自动备份就补一份, 保留最近 30 份。进"备份恢复", 选昨天或前天的备份, 点"还原"。
3. 第三道: 手动下载过的备份文件如果你之前在"备份恢复"页点过"下载"把 .db 文件存到过 U 盘, 那是最稳的。软件没有"上传恢复"按钮, 恢复方法是: 关闭软件, 把这个 .db 文件复制到数据目录下的 backups 子文件夹里(默认在 D:\乡村管理系统\data\backups\), 文件名只能用英文字母、数字、短横线, 且必须以 .db 结尾(中文文件名会被拒绝), 重新打开软件, 进"备份恢复", 列表里就能看到这个文件, 点"恢复"。
4. 别做的事在搞清楚状况前, 不要重装软件, 不要删 data 目录, 不要重新初始化。这些操作会让恢复变难。