疑難排解Troubleshooting

插件啟動失敗，說連接埠已被占用

預設埠 8080 很常被其他軟體占用。改 http.port，或查出占用者：

Windows: netstat -ano | findstr :8080
Linux  : lsof -i :8080

啟動時說找不到資料庫驅動

第一次啟動需要連得上 Maven 下載驅動。確認伺服器能對外連線、防火牆沒有擋住，然後重啟。

設定了 require-key 卻還是拿得到資料

auth.enabled 沒有開。總開關為 false 時所有端點層與欄位層設定都不生效。啟動時會有警告訊息提醒。

速率限制沒有作用

依序檢查三項：rate-limit.enabled 是否為 true；來源 IP 是否在 exempt-ips 內（預設含 127.0.0.1，本機測試永遠不會被擋）；以及是否帶了有效金鑰而符合 exempt-authenticated。

/api/docs 打不開

預設關閉。設 web.docs: true 後重啟或 /serverapi reload。

所有訪客共用同一個限流額度

你在反向代理後方，來源都是代理主機。開啟 real-ip.enabled 並把代理位址填進 trusted-proxies。

處罰紀錄裡沒有警告／禁言／監禁

這三類來自 CMI，未安裝就不會出現。

The plugin fails to start, saying the port is in use

The default 8080 is claimed by a lot of software. Change http.port, or find what is holding it:

Windows: netstat -ano | findstr :8080
Linux  : lsof -i :8080

It reports a missing database driver at startup

The first launch needs to reach Maven to download the drivers. Confirm the server has outbound network access and is not firewalled, then restart.

I set require-key but the data is still readable

auth.enabled is off. While the master switch is false, neither the per-endpoint nor the per-field settings take effect. The plugin warns about this at startup.

Rate limiting does nothing

Check three things in order: whether rate-limit.enabled is true; whether the source IP is in exempt-ips (which includes 127.0.0.1 by default, so local testing is never limited); and whether the request carries a valid key and is covered by exempt-authenticated.

/api/docs will not open

It is off by default. Set web.docs: true, then restart or run /serverapi reload.

Every visitor shares one rate limit bucket

You are behind a reverse proxy, so all requests appear to come from it. Turn on real-ip.enabled and list the proxy address in trusted-proxies.

No warnings / mutes / jails in the punishment records

Those three come from CMI. Without it installed they simply do not appear.