Docs/yanshan-meeting-bigdata/Troubleshooting
Runbook

Troubleshooting

Common API errors and debugging

Objective

This runbook helps you diagnose and resolve common API errors and connectivity issues with the Yanshan Meeting Big Data System, and should be used whenever the web interface is unreachable, API requests fail, or the server behaves unexpectedly after launch.

Scope

This runbook covers:

  • Server startup failures after double-clicking 启动系统.bat
  • API layer errors (unexpected HTTP status codes, malformed responses)
  • Local access failures (http://localhost:3005 unreachable)
  • LAN access failures (http://<secretary-IP>:3005 unreachable from other devices)
  • Port 3005 conflicts

This runbook does not cover:

  • Installation or initial setup (see the Getting Started guide)
  • Application-level business logic or data entry errors
  • Network infrastructure configuration beyond the host machine (e.g., router or switch settings)
  • Issues arising from operating systems other than Windows 10
Prerequisites

Before working through this runbook, confirm you have the following:

  • Windows 10 host machine operated by the meeting secretary (书记员)
  • The portable package (yanshan-meeting-bigdata-win10-portable-v5.zip) already extracted to a local folder (e.g., D:\盐山会议大数据系统)
  • A web browser installed on the local machine or the remote device you are testing from
  • Access to the secretary's computer — either physically or via a remote-desktop session — to inspect the console output produced by 启动系统.bat
  • The secretary's computer IP address on the LAN (required for LAN access troubleshooting only)
Steps

Work through the numbered steps below in order, stopping as soon as the issue is resolved.

1. Confirm the server is running

What to do: Check whether 启动系统.bat has been started and its console window is still open.

Action: Look at the secretary's desktop for an open black console (command-prompt) window. This window must remain open for the server to keep running.

Success looks like: The console window is open and shows no red error text. You may see startup log lines indicating the server is listening.

2. Restart the server if the console window is closed or shows an error

What to do: If the console window was closed or printed an error, stop any lingering process and relaunch.

Action:

  1. Close any existing console window associated with 启动系统.bat.
  2. Open Task Manager (Ctrl + Shift + Esc), go to Details, and check whether node.exe is still running. If it is, select it and click End Task.
  3. Navigate to the extraction folder (e.g., D:\盐山会议大数据系统) and double-click 启动系统.bat.

Success looks like: A new console window opens without errors, and the server starts listening on port 3005.

3. Test local access

What to do: Verify the API layer is responding on the local machine.

Action: Open a browser on the secretary's computer and navigate to:

http://localhost:3005

Success looks like: The meeting big-data management interface loads in the browser. Any API requests made by the interface return HTTP 2xx responses.

4. Diagnose a port conflict on 3005

What to do: If http://localhost:3005 returns a connection-refused error, another process may already be using port 3005.

Action:

  1. Open Command Prompt (search for cmd in the Start menu).
  2. Run the following command to identify which process is using port 3005: 
    netstat -ano | findstr :3005
  3. Note the PID in the rightmost column.
  4. In Task Manager → Details, find the process with that PID.
  5. If the process is not node.exe from the portable package, end it, then relaunch 启动系统.bat.

Success looks like: After ending the conflicting process and relaunching, http://localhost:3005 loads correctly.

5. Check Windows Firewall for LAN access issues

What to do: If other devices on the LAN cannot reach http://<secretary-IP>:3005, the Windows Firewall may be blocking inbound connections on port 3005.

Action:

  1. On the secretary's computer, open Windows Defender Firewall with Advanced Security (search in Start menu).
  2. Select Inbound Rules → New Rule.
  3. Choose Port, click Next.
  4. Select TCP, enter 3005 as the specific local port, click Next.
  5. Select Allow the connection, click Next.
  6. Apply the rule to Domain, Private, and Public profiles as appropriate for your meeting environment.
  7. Give the rule a name (e.g., Yanshan Meeting Port 3005) and click Finish.

Success looks like: From another device on the same LAN, navigating to http://<secretary-IP>:3005 loads the web interface.

6. Confirm the secretary's computer IP address

What to do: If LAN clients are using the wrong IP address, they will never reach the server.

Action:

  1. On the secretary's computer, open Command Prompt and run: 
    ipconfig
  2. Locate the IPv4 Address under the active network adapter (typically shown as 192.168.x.x or 10.x.x.x).
  3. Share this IP address with anyone who needs LAN access. They should open: 
    http://<secretary-IP>:3005

Success looks like: LAN clients can load the interface using the correct IP.

7. Inspect API error responses

What to do: If the interface loads but specific API requests fail (e.g., data does not appear, actions produce errors), inspect the raw HTTP responses.

Action:

  1. Open the browser's Developer Tools (F12) on the machine experiencing the issue.
  2. Go to the Network tab and reproduce the failing action.
  3. Click the failed request and review:
    • Status code — note the exact HTTP status (e.g., 400, 404, 500).
    • Response body — note any error message text returned by the API layer.
  4. Record the full request URL, HTTP method, status code, and response body for reference.

Success looks like: You have identified the specific endpoint and error details needed to proceed with further diagnosis or escalation.

8. Verify the extraction is complete and untampered

What to do: A partial or corrupted extraction can cause the server to start but the API layer to malfunction.

Action:

  1. Confirm that node.exe is present inside the extraction folder alongside 启动系统.bat.
  2. If any files appear missing, delete the extraction folder and re-extract yanshan-meeting-bigdata-win10-portable-v5.zip to a clean location (e.g., D:\盐山会议大数据系统).
  3. Relaunch 启动系统.bat.

Success looks like: The server starts cleanly and http://localhost:3005 responds correctly.

Verification

After completing the relevant steps above, confirm resolution with the following checks:

  1. Server console is open and stable — the console window launched by 启动系统.bat is running without error output.
  2. Local access confirmed — opening http://localhost:3005 in a browser on the secretary's computer displays the meeting big-data management interface without HTTP errors.
  3. API layer responding — the browser's Network tab shows that requests made by the interface return HTTP 2xx status codes.
  4. LAN access confirmed (if applicable) — at least one other device on the same local network successfully loads http://<secretary-IP>:3005 in its browser.
  5. No port conflict — running netstat -ano | findstr :3005 shows only the bundled node.exe process bound to port 3005.
Rollback

The actions in this runbook are largely diagnostic and non-destructive. However, if a step introduced a change that caused new problems, reverse it as follows:

  • Firewall rule added (Step 5): Open Windows Defender Firewall with Advanced Security → Inbound Rules, locate the rule named Yanshan Meeting Port 3005, right-click it, and select Delete.
  • Conflicting process ended (Step 4): If you inadvertently ended a process that should have been running, restart the relevant application from its own launcher. The portable package itself is unaffected — simply re-run 启动系统.bat.
  • Re-extraction performed (Step 8): If the newly extracted copy does not work, delete it and restore from a known-good backup of yanshan-meeting-bigdata-win10-portable-v5.zip, then re-extract.
  • Server relaunched: If the relaunch made things worse, close the console window, wait 10 seconds for the port to release, and double-click 启动系统.bat again.

The portable package does not modify system-level settings (registry, PATH, or installed software), so no system-level rollback is required.

Escalation

If you have completed all applicable steps in this runbook and the system is still not functioning correctly, escalate using the information below.

Who to contact: Contact the development or support team responsible for the yanshan-meeting-bigdata project via the repository's issue tracker (accessible from the same Releases page where the ZIP package was downloaded).

Information to provide when escalating:

  1. Package version — confirm you are using yanshan-meeting-bigdata-win10-portable-v5.zip.
  2. Host OS — confirm Windows 10 and note the edition (e.g., Home, Pro) and build number (Settings → System → About).
  3. Symptom description — describe exactly what fails: is the server not starting, is http://localhost:3005 unreachable, or are specific API requests returning errors?
  4. Console output — copy and paste the full text from the 启动系统.bat console window at the time of failure.
  5. API error details — if an API request failed, provide the full request URL, HTTP method, HTTP status code, and the complete response body captured from the browser's Network tab.
  6. Steps already attempted — list every step from this runbook you completed and the result of each.
  7. netstat output — paste the output of netstat -ano | findstr :3005 from the secretary's computer.