常见问题
❓ 常见问题解答
遇到问题？先看看这里
🐳 部署相关
Docker 容器无法启动？
1. 检查端口是否被占用
bash
lsof -i:80002. 查看容器日志
bash
docker logs navlink-app3. 确保数据目录权限正确
bash
chmod -R 755 data plugins logs忘记管理员密码？
删除认证数据库重新初始化：
bash
# 停止容器
docker stop navlink-app
# 删除认证数据库
rm data/auth.db
# 重启容器（会使用默认密码 admin123）
docker start navlink-app⚠️ 这将重置所有用户账户！其他数据不受影响。
如何备份数据？
方式一：后台导出
登录后台 → 数据管理 → 导出配置
方式二：命令行备份
bash
# 停止容器
docker stop navlink-app
# 备份整个 data 目录
tar -czvf navlink-backup-$(date +%Y%m%d).tar.gz data/
# 重启容器
docker start navlink-app升级后需要重新激活？
确保 docker-compose.yml 中配置了固定的 hostname：
yaml
services:
navlink:
image: ghcr.io/txwebroot/navlink-releases:latest
hostname: navlink-app # 必须固定！这样升级后容器指纹不会变化，无需重新激活。
解决 Docker 管理连不上 VPS？
为了能从本地操作远程 Docker，NavLink 在 SSH 连接成功后，会尝试在远程服务器上运行 socat 命令进行流量转发。如果连接失败，请检查以下三项：
1. 检查并安装 socat
如果 VPS 上没有安装 socat 可能会报错。请用终端连上服务器，输入 socat -V 查看是否存在。
- 解决：在服务器上运行
yum install socat(CentOS) 或apt install socat(Ubuntu/Debian)。NOTE
在 v2.1.2 及以上版本的 Docker 插件中，系统会尝试自动静默安装
socat（需具备 root 或 sudo 权限）。但为了确保连接稳定性，建议优先手动登录服务器执行socat -V确认环境就绪。
2. Docker 权限问题
如果你在 Docker 插件里填写的 SSH 用户（比如不是 root）没有加入 docker 用户组，它就无法读取 Docker API 套接字文件。
- 解决：将该用户加入 docker 用户组：bash
sudo usermod -aG docker <用户名>
3. SSH 隧道转发功能
NavLink 需要使用 SSH 的 隧道转发（SSH Tunneling） 功能。请检查远程服务器 /etc/ssh/sshd_config 文件，看是否存在 AllowTcpForwarding no。如果是 no，Docker 插件将无法通过隧道传输 Docker API 数据，导致连接失败。
- 解决：将
AllowTcpForwarding设为yes，然后重启 SSH 服务：systemctl restart sshd。
🔧 功能相关
搜索没有结果？
- ✅ 确保已添加链接分类和链接
- ✅ 检查搜索关键词是否匹配标题或描述
- ✅ 拼音搜索需要输入完整拼音或首字母
AI 对话报错？
- ✅ 检查 API Key 是否正确
- ✅ 确认 Base URL 格式（需包含
/v1） - ✅ 检查网络连接（部分 API 可能需要代理）
常用配置：
| 提供商 | Base URL |
|---|---|
| DeepSeek | https://api.deepseek.com/v1 |
| OpenAI | https://api.openai.com/v1 |
插件安装失败？
- ✅ 确保
plugins目录已挂载 - ✅ 检查磁盘空间是否充足
- ✅ 查看后台日志获取详细错误
bash
docker logs navlink-app --tail 50链接健康检测不准确？
部分网站有反爬机制，可能误判为失效。可以：
- 手动标记为健康
- 排除特定域名
- 调整检测超时时间
⚡ 性能优化
响应缓慢怎么办？
- ✅ 检查服务器配置（建议 1GB+ 内存）
- ✅ 减少首页显示的链接数量
- ✅ 关闭不使用的插件
- ✅ 启用 Redis 缓存（可选）
数据库过大怎么办？
清理历史日志：
bash
docker exec -it navlink-app sh -c "rm -rf logs/*"📌 其他问题
如何修改端口？
修改 .env 文件中的 PORT 变量：
bash
PORT=3001 # 改为您需要的端口然后重启：
bash
docker compose up -d如何查看版本号？
- 登录后台 → 系统设置 → 系统升级
- 或查看容器镜像：
docker inspect navlink-app | grep Image