1 常见问题与故障处理

访问与运行

Q：服务在运行，但浏览器打不开页面？

ss -tlnp | grep lynx-board        # 确认实际监听端口（可能自动切换过）
cat /opt/lynx-board/data/port.json
curl -s http://localhost:<端口>/api/admin/check   # 本机接口是否响应
sudo ufw status                   # 防火墙是否放行该端口

确认使用正确的端口与设备 IP；若经反向代理，检查转发目标端口。

Q：服务反复重启怎么办？

journalctl -u lynx-board -n 100 --no-pager

常见原因：端口被占满、数据目录权限异常、磁盘空间不足。查看日志中的报错定位并处理。

Q：页面提示「登录已过期，请重新登录」？
登录状态默认 7 天，重新登录即可；如需延长，见「访问端口与服务管理」中调整登录有效期的方法。

Q：注册是开放的，安全吗？
开放注册便于团队自助加入，但意味着能访问地址的人都能注册。请限制网络来源（防火墙、安全代理），并始终通过 HTTPS 对外访问。

账户与数据

Q：忘记密码怎么办？

• 普通成员忘记密码：管理员登录后在「账户管理」中对其「重置密码」。
• 管理员忘记密码：系统不提供自助找回，可移走数据文件重新初始化管理员，再导入看板备份：

sudo systemctl stop lynx-board
sudo mv /opt/lynx-board/data/lynx-board.db /var/backups/lynx-board-forgot-$(date +%F).db
sudo systemctl start lynx-board

服务以空库启动后，浏览器访问设备地址会重新进入「创建管理员」页面；随后通过顶部「导入 JSON」载入此前导出的看板备份。注意：成员账户与邮件提醒配置不包含在看板导出文件内，恢复后需重建。

Q：数据存在哪里？如何备份？
数据集中在 /opt/lynx-board/data/lynx-board.db 单文件中，停服后拷贝即完成备份，恢复时放回原路径重启服务，详见「数据备份与升级」。

Q：如何把数据迁移到新设备？
在新设备就绪后停止服务，将旧设备的数据文件拷入 /opt/lynx-board/data/，启动服务并登录验证。

Q：数据文件损坏或启动报数据库错误？
停止服务，用最近备份替换数据文件后重启；无备份时移走损坏文件，服务会以空库启动，再通过「导入 JSON」恢复看板数据。

Q：data/ 目录下出现 port.json 正常吗？
正常，它记录自动选定的监听端口，由程序自动维护，无需手工编辑。

升级与迁移

Q：升级会丢失数据或配置吗？
不会。升级显式保留数据目录与 /etc/lynx-board/env，看板、成员账户、登录状态与提醒设置全部延续。

Q：升级失败怎么办？
升级过程任一校验失败都会自动回滚到升级前版本，服务照常用旧版运行；用 journalctl -u lynx-board -n 50 --no-pager 查看失败原因，处理后重新安装新版即可。

Q：升级需要重新配置端口和登录有效期吗？
不需要，相关配置随升级保留；除非主动修改，否则保持不变。

Q：卸载后数据还在吗？
sudo dpkg -r lynx-board 只移除程序，数据与配置保留，重装即继续使用；sudo dpkg -P lynx-board 会连同数据一并删除，执行前请确认已备份。

Q：设备系统重装后如何恢复？
系统重装后由生产环节重新部署程序，随后按「数据备份与升级」还原数据文件，重启登录即可；如更换了设备，按「迁移到新设备」处理。