From f2b4525967a5ed3bff18ff1efbad6cd1a8de8eca Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Tue, 7 Apr 2026 09:50:07 +0800 Subject: [PATCH] docs: add Maven mirror config and troubleshooting guide for China developers (#233) - Add Aliyun mirror config in server/.mvn/settings.xml - Update maven-wrapper.properties to use Aliyun mirror for Maven distribution - Add detailed error messages in Makefile when backend startup fails - Add troubleshooting section in quickstart.md for China developers - Add FAQ entry for local development startup issues - Update README with link to local development guide --- Makefile | 19 ++++-- README.md | 2 + README_zh.md | 2 + docs/skillhub/en/faq.md | 71 ++++++++++++++++++++ docs/skillhub/en/quickstart.md | 33 +++++++++ docs/skillhub/faq.md | 71 ++++++++++++++++++++ docs/skillhub/quickstart.md | 33 +++++++++ server/.mvn/settings.xml | 16 +++++ server/.mvn/wrapper/maven-wrapper.properties | 2 +- 9 files changed, 244 insertions(+), 5 deletions(-) create mode 100644 server/.mvn/settings.xml diff --git a/Makefile b/Makefile index 8f262ab5..60e1f488 100644 --- a/Makefile +++ b/Makefile @@ -71,10 +71,21 @@ dev-all: ## 一键启动本地开发环境（依赖 + scanner + 后端 + 前端 $(DEV_PROCESS) start --pid-file $(DEV_SERVER_PID) --log-file $(DEV_SERVER_LOG) --cwd server -- /bin/sh -lc '$(DEV_SERVER_PREPARE) && exec env $(DEV_SERVER_SCANNER_ENV) $(DEV_SERVER_CMD)' >/dev/null; \ fi; \ done; \ - if [ "$$backend_ready" -ne 1 ]; then \ - echo "Backend failed to become ready. Check $(DEV_SERVER_LOG)"; \ - exit 1; \ - fi + if [ "$$backend_ready" -ne 1 ]; then \ + echo ""; \ + echo "Backend failed to become ready. Check $(DEV_SERVER_LOG)"; \ + echo ""; \ + echo "Common issues:"; \ + echo " 1. Maven dependency download failed (network timeout)"; \ + echo " -> Configure mirror in ~/.m2/settings.xml"; \ + echo " -> See: https://maven.aliyun.com/mvn/guide"; \ + echo " 2. Java version mismatch (requires Java 21+)"; \ + echo " -> Run: java -version"; \ + echo " 3. Port 8080 already in use"; \ + echo " -> Run: lsof -i :8080"; \ + echo ""; \ + exit 1; \ + fi @echo "Waiting for scanner on $(DEV_SCANNER_URL) ..." @scanner_ready=0; \ for i in $$(seq 1 30); do \ diff --git a/README.md b/README.md index 2edab733..e96ef1e5 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,8 @@ If deployment runs into problems, clear the existing runtime home and retry. make dev-all ``` +> **For developers in China**: If Maven dependency download times out, configure Aliyun mirror. See [Local Development Guide](https://iflytek.github.io/skillhub/quickstart.html#本地开发) for details. + Then open: - Web UI: `http://localhost:3000` diff --git a/README_zh.md b/README_zh.md index 20548b05..86df8120 100644 --- a/README_zh.md +++ b/README_zh.md @@ -126,6 +126,8 @@ make dev-backend # 仅后端 make dev-web # 仅前端 ``` +> **国内开发者**：如果 Maven 依赖下载超时，需配置阿里云镜像。详见 [本地开发指南](https://iflytek.github.io/skillhub/quickstart.html#本地开发)。 + ### 常用命令 ```bash diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index 2aec46ff..368cc5fa 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -131,3 +131,74 @@ A: You can get help through the following channels: - **GitHub Issues**: https://github.com/iflytek/skillhub/issues - **Documentation**: Refer to the project README.md - **Community Discussions**: https://github.com/iflytek/skillhub/discussions + +## Q: What should I do if local development fails to start? + +A: When `make dev-all` fails to start the backend, detailed error messages will be displayed. Common issues: + +### 1. Maven dependency download failed (network timeout) + +**Symptoms**: Backend logs show `Could not transfer artifact` or connection timeout + +**Solution**: Configure Aliyun mirror + +```bash +# Copy the project's built-in mirror configuration to user directory +mkdir -p ~/.m2 +cp server/.mvn/settings.xml ~/.m2/settings.xml +``` + +Or manually create `~/.m2/settings.xml`: + +```xml + + + + + aliyun + https://maven.aliyun.com/repository/public + central + + + +``` + +Reference: [Aliyun Maven Mirror Configuration Guide](https://maven.aliyun.com/mvn/guide) + +### 2. Java version mismatch + +**Symptoms**: `Unsupported class file major version` or `java.lang.NoSuchMethodError` + +**Solution**: Install Java 21+ + +```bash +# macOS +brew install openjdk@21 + +# Verify version +java -version +``` + +### 3. Port already in use + +**Symptoms**: `Port 8080 already in use` + +**Solution**: + +```bash +# Find the process using the port +lsof -i :8080 + +# Terminate the process +kill -9 +``` + +### 4. View detailed logs + +If the above solutions don't help, check the backend logs: + +```bash +make dev-logs SERVICE=backend +# Or view directly +cat .dev/server.log +``` diff --git a/docs/skillhub/en/quickstart.md b/docs/skillhub/en/quickstart.md index 1f2c0289..f2b183b9 100644 --- a/docs/skillhub/en/quickstart.md +++ b/docs/skillhub/en/quickstart.md @@ -64,6 +64,39 @@ cd skillhub make dev-all ``` +### Notes for Developers in China + +If `make dev-all` fails to start the backend, common causes include: + +1. **Maven dependency download timeout** + + The project includes a built-in Aliyun mirror configuration (`server/.mvn/settings.xml`), but Maven does not automatically read project-level settings. You need to configure it manually: + + ```bash + # Option 1: Copy to user directory (recommended) + mkdir -p ~/.m2 + cp server/.mvn/settings.xml ~/.m2/settings.xml + + # Option 2: Specify on each build + cd server && ./mvnw -s .mvn/settings.xml package + ``` + +2. **Java version mismatch** + + SkillHub requires Java 21+: + ```bash + java -version + ``` + +3. **Port conflict** + + Check if port 8080 is in use: + ```bash + lsof -i :8080 + ``` + +For detailed troubleshooting steps, see [FAQ](faq.md#local-development-startup-failure). + ## Logging In ### Option 1: Use the Built-in Admin Account diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index 7768cb35..6f9abe71 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -131,3 +131,74 @@ A: 可以通过以下方式获取帮助： - **GitHub Issues**: https://github.com/iflytek/skillhub/issues - **文档**: 参考项目 README.md - **社区讨论**: https://github.com/iflytek/skillhub/discussions + +## Q: 本地开发启动失败怎么办？ + +A: `make dev-all` 后端启动失败时，会显示详细的错误提示。常见问题： + +### 1. Maven 依赖下载失败（网络超时） + +**症状**：后端日志显示 `Could not transfer artifact` 或连接超时 + +**解决方案**：配置阿里云镜像 + +```bash +# 复制项目内置的镜像配置到用户目录 +mkdir -p ~/.m2 +cp server/.mvn/settings.xml ~/.m2/settings.xml +``` + +或手动创建 `~/.m2/settings.xml`： + +```xml + + + + + aliyun + https://maven.aliyun.com/repository/public + central + + + +``` + +参考：[阿里云 Maven 镜像配置指南](https://maven.aliyun.com/mvn/guide) + +### 2. Java 版本不匹配 + +**症状**：`Unsupported class file major version` 或 `java.lang.NoSuchMethodError` + +**解决方案**：安装 Java 21+ + +```bash +# macOS +brew install openjdk@21 + +# 验证版本 +java -version +``` + +### 3. 端口被占用 + +**症状**：`Port 8080 already in use` + +**解决方案**： + +```bash +# 查看占用端口的进程 +lsof -i :8080 + +# 终止进程 +kill -9 +``` + +### 4. 查看详细日志 + +如果以上方案无法解决，查看后端日志： + +```bash +make dev-logs SERVICE=backend +# 或直接查看 +cat .dev/server.log +``` diff --git a/docs/skillhub/quickstart.md b/docs/skillhub/quickstart.md index f913e85b..141c6fef 100644 --- a/docs/skillhub/quickstart.md +++ b/docs/skillhub/quickstart.md @@ -64,6 +64,39 @@ cd skillhub make dev-all ``` +### 国内开发者注意事项 + +如果 `make dev-all` 后端启动失败，常见原因： + +1. **Maven 依赖下载超时** + + 项目已内置阿里云镜像配置（`server/.mvn/settings.xml`），但 Maven 不会自动读取项目级配置。需要手动配置： + + ```bash + # 方式一：复制到用户目录（推荐） + mkdir -p ~/.m2 + cp server/.mvn/settings.xml ~/.m2/settings.xml + + # 方式二：每次构建时指定 + cd server && ./mvnw -s .mvn/settings.xml package + ``` + +2. **Java 版本不匹配** + + SkillHub 要求 Java 21+： + ```bash + java -version + ``` + +3. **端口冲突** + + 检查 8080 端口是否被占用： + ```bash + lsof -i :8080 + ``` + +详细的错误排查步骤，请查看 [常见问题](faq.md#本地开发启动失败)。 + ## 登录系统 ### 方式一：使用内置管理员账号 diff --git a/server/.mvn/settings.xml b/server/.mvn/settings.xml new file mode 100644 index 00000000..48462dae --- /dev/null +++ b/server/.mvn/settings.xml @@ -0,0 +1,16 @@ + + + + + + aliyun + Aliyun Maven Mirror + https://maven.aliyun.com/repository/public + central + + + + diff --git a/server/.mvn/wrapper/maven-wrapper.properties b/server/.mvn/wrapper/maven-wrapper.properties index 71ea75a7..0f16952f 100644 --- a/server/.mvn/wrapper/maven-wrapper.properties +++ b/server/.mvn/wrapper/maven-wrapper.properties @@ -1,3 +1,3 @@ wrapperVersion=3.3.4 distributionType=only-script -distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.13/apache-maven-3.9.13-bin.zip +distributionUrl=https://maven.aliyun.com/repository/public/org/apache/maven/apache-maven/3.9.13/apache-maven-3.9.13-bin.zip