|
2 | 2 | title: Debugging Guide |
3 | 3 | --- |
4 | 4 |
|
5 | | -Enter the server console and use `pm2 ls` to check the current list of running processes. |
6 | | -Under normal conditions, there should be four running processes: `hydrooj`, `hydro-sandbox`, `mongodb`, and `caddy`. |
7 | | -If processes are missing, run `pm2 stop all`, then `pm2 del all`, and rerun the installation script. |
| 5 | +## Process Management |
8 | 6 |
|
9 | | -Check whether each process has started (status is online and uptime is at least one minute). |
| 7 | +Access your server console and use `pm2 ls` to view the status of running processes. |
| 8 | +A healthy Hydro instance typically has four processes: `hydrooj`, `hydro-sandbox`, `mongodb`, and `caddy`. |
10 | 9 |
|
11 | | -If caddy cannot start, it is usually due to port conflicts or errors in `~/.hydro/Caddyfile`; you can try `cd ~/.hydro && caddy run` for details. |
12 | | -If hydro-sandbox cannot start, it is usually due to insufficient permissions / kernel version too low; use `pm2 logs hydro-sandbox --lines 100` for details. |
13 | | -If hydrooj cannot start / does not run properly after starting, see the section below. |
| 10 | +If any processes are missing or failing to start: |
| 11 | +1. Run `pm2 stop all` and `pm2 del all`. |
| 12 | +2. Rerun the installation script to restore the default process configuration. |
14 | 13 |
|
15 | | -## hydrooj |
| 14 | +### Troubleshooting Process Failures |
16 | 15 |
|
17 | | -After stopping with `pm2 stop hydrooj`, run command `hydrooj` directly to run Hydro in the foreground for easier log inspection. |
| 16 | +- **Caddy**: Usually fails due to port conflicts (port 80/443 already in use) or syntax errors in `~/.hydro/Caddyfile`. Run `cd ~/.hydro && caddy run` in the foreground to see detailed error messages. |
| 17 | +- **Hydro-Sandbox**: Often fails due to insufficient permissions or an outdated kernel. Check logs with `pm2 logs hydro-sandbox --lines 100`. |
| 18 | +- **HydroOJ**: If the main service fails, refer to the section below. |
18 | 19 |
|
19 | | -1. Try updating to the latest version and check whether it works properly. |
20 | | -2. Back up the plugin list with `cp ~/.hydro/addon.json ~/.hydro/addon.json.bak`. |
21 | | -3. Use `hydrooj addon list` to view plugins, and disable all non-official plugins (those without the `@hydrooj/` prefix) with `hydrooj addon remove <name>`. |
22 | | -4. Restart and check whether it runs properly. |
23 | | -5. If it works, the issue is caused by a third-party plugin. Try re-enabling the plugins you just disabled one by one and check when the issue appears, then contact the plugin provider. |
24 | | -6. If it still does not run properly, provide the development team with the full log from Hydro startup to fault occurrence for troubleshooting. |
| 20 | +## Debugging HydroOJ |
25 | 21 |
|
26 | | -## Frontend issues |
| 22 | +To inspect detailed logs, stop the background process and run Hydro in the foreground: |
| 23 | +1. `pm2 stop hydrooj` |
| 24 | +2. Run the command `hydrooj` directly. |
27 | 25 |
|
28 | | -This refers to frontend pages failing to load (continuous spinner or yellow/red error prompts at the bottom-left). |
| 26 | +**Suggested Steps:** |
| 27 | +1. **Update**: Ensure you are running the latest version. |
| 28 | +2. **Plugins**: Third-party plugins are a common cause of crashes. |
| 29 | + - Back up your plugin list: `cp ~/.hydro/addon.json ~/.hydro/addon.json.bak`. |
| 30 | + - View active plugins: `hydrooj addon list`. |
| 31 | + - Remove non-official plugins (those without the `@hydrooj/` prefix): `hydrooj addon remove <name>`. |
| 32 | +3. **Restart**: Check if the system runs correctly without third-party plugins. If it does, re-enable them one by one to identify the culprit. |
| 33 | +4. **Support**: If the issue persists, provide the development team with the full console output from startup until the error occurs. |
| 34 | + |
| 35 | +## Frontend Issues |
| 36 | + |
| 37 | +Symptoms include pages failing to load, infinite loading spinners, or error prompts (yellow/red) at the bottom-left of the screen. |
| 38 | + |
| 39 | +1. **Clear Cache**: Press `Ctrl+Shift+Delete` to clear your browser cache and reload. |
| 40 | +2. **Browser Version**: Ensure you are using the latest version of Chrome or a Chromium-based browser. |
| 41 | +3. **Disable Extensions**: Browser extensions can sometimes interfere with page scripts. |
| 42 | +4. **Developer Tools**: Press `F12`, go to the **Console** tab for script errors, and the **Network** tab to identify failed requests. |
| 43 | +5. **Report**: When seeking help in the user group, please include screenshots of both the Console and Network tabs. |
29 | 44 |
|
30 | | -1. Press `Ctrl+Shift+Delete` to clear browser cache and try again. |
31 | | -2. Update Chrome to the latest version and try again. |
32 | | -3. Same as above, try disabling third-party plugins. |
33 | | -3. If the issue still persists, open F12 Developer Tools, go to the `Console` tab, and check for error messages. |
34 | | -4. Open the `Network` tab and check for failed requests. |
35 | | -5. Report the issue in the group and attach screenshots of the above. |
|
0 commit comments