Kikoeru 部署常见报错排查：端口占用、权限不足、路径错误

端口 8888 被占用

现象：启动时报错 EADDRINUSE 或 Windows exe 双击后闪退。

排查：

# Linux
sudo lsof -i :8888

# Windows（PowerShell）
netstat -ano | findstr :8888

解决：

• 关掉占端口的进程，或改 Kikoeru 端口
• 改端口：编辑 config/config.json，把 port 改成别的（比如 8889），重启

Docker 容器启动失败（exit code 1）

现象：docker compose up -d 后容器秒退。

排查：

docker logs kikoeru          # 看容器日志
docker inspect kikoeru       # 看容器配置

常见原因：

1. 卷挂载路径写错：左边的宿主机路径不存在，Docker 创建了空目录挂载进去。检查路径拼写。
2. sqlite 目录权限问题：容器内进程没写权限。chmod 一下 chmod -R 777 sqlite/ 试试。
3. Node.js 内存不足：大音声库扫描可能吃内存。Docker 限制了内存的话，放宽。

容器能启动但 Web 界面打不开

排查清单：

1. 容器是不是在跑：docker ps 看状态是 Up
2. 端口映射对不对：docker port kikoeru 看实际映射
3. 防火墙有没有放行（ufw、云安全组）
4. 服务器 IP 对不对——别用 localhost 去连远程服务器

Web 界面能打开但根文件夹添加后扫描不到文件

最常见原因：路径配错了。

• Docker 用户填了宿主机路径（比如 /mnt/media/VoiceWork）而不是容器内路径（比如 /usr/src/kikoeru/VoiceWork）
• Windows 用户填了不存在的路径
• 音声文件不在你以为的那个目录结构下（比如番号和音频文件混在一起）

排查：

# Docker：进去看容器里有没有文件
docker exec -it kikoeru ls /usr/src/kikoeru/VoiceWork

# 如果这里是空的，说明宿主机路径挂错了
# 如果这里有文件，说明路径没问题，继续看其他

扫描卡住不动

扫描进度长时间停在某个百分比或一直 0%，参考 扫描卡住排查。

npm install 失败

常见原因：

• Node.js 版本过旧：Kikoeru 建议 Node.js 18+。node -v 确认一下
• sqlite3 原生模块编译失败：Windows 下需要装 Visual Studio Build Tools，或者用预编译的二进制（切换到 Python / make / g++ 完整工具链后重试）
• 网络问题：换国内源 npm config set registry https://registry.npmmirror.com

元数据抓取一直失败（封面和标签全空）

DLSite 可能对某些 IP 或频次有反爬限制。

• 先确认你的网络能访问 DLSite
• 重试扫描：有些作品第一次没抓到，第二次就成功了
• 如果持续失败，考虑手动整理或换网络环境