mirror of
https://github.com/iflytek/skillhub.git
synced 2026-10-09 03:17:52 +00:00
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
This commit is contained in:
XiaoSeS
GitHub
parent
0b84e4eff3
commit
f2b4525967
9 changed files with 244 additions and 5 deletions
19
Makefile
19
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 \
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -126,6 +126,8 @@ make dev-backend # 仅后端
|
|||
make dev-web # 仅前端
|
||||
```
|
||||
|
||||
> **国内开发者**：如果 Maven 依赖下载超时，需配置阿里云镜像。详见 [本地开发指南](https://iflytek.github.io/skillhub/quickstart.html#本地开发)。
|
||||
|
||||
### 常用命令
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<settings>
|
||||
<mirrors>
|
||||
<mirror>
|
||||
<id>aliyun</id>
|
||||
<url>https://maven.aliyun.com/repository/public</url>
|
||||
<mirrorOf>central</mirrorOf>
|
||||
</mirror>
|
||||
</mirrors>
|
||||
</settings>
|
||||
```
|
||||
|
||||
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 <PID>
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<settings>
|
||||
<mirrors>
|
||||
<mirror>
|
||||
<id>aliyun</id>
|
||||
<url>https://maven.aliyun.com/repository/public</url>
|
||||
<mirrorOf>central</mirrorOf>
|
||||
</mirror>
|
||||
</mirrors>
|
||||
</settings>
|
||||
```
|
||||
|
||||
参考：[阿里云 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 <PID>
|
||||
```
|
||||
|
||||
### 4. 查看详细日志
|
||||
|
||||
如果以上方案无法解决，查看后端日志：
|
||||
|
||||
```bash
|
||||
make dev-logs SERVICE=backend
|
||||
# 或直接查看
|
||||
cat .dev/server.log
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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#本地开发启动失败)。
|
||||
|
||||
## 登录系统
|
||||
|
||||
### 方式一：使用内置管理员账号
|
||||
|
|
|
|||
16
server/.mvn/settings.xml
Normal file
16
server/.mvn/settings.xml
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0
|
||||
https://maven.apache.org/xsd/settings-1.2.0.xsd">
|
||||
|
||||
<mirrors>
|
||||
<mirror>
|
||||
<id>aliyun</id>
|
||||
<name>Aliyun Maven Mirror</name>
|
||||
<url>https://maven.aliyun.com/repository/public</url>
|
||||
<mirrorOf>central</mirrorOf>
|
||||
</mirror>
|
||||
</mirrors>
|
||||
|
||||
</settings>
|
||||
2
server/.mvn/wrapper/maven-wrapper.properties
vendored
2
server/.mvn/wrapper/maven-wrapper.properties
vendored
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue