1. 环境准备Docker与Docker Compose安装第一次接触OpenSPG时我花了两天时间才把环境折腾明白。现在回头看其实只要把Docker和Docker Compose装对版本后面基本不会踩坑。建议直接用官方脚本安装比手动配置省心得多。对于Linux系统用这个命令一键安装Dockercurl -fsSL https://get.docker.com | sh装完记得把当前用户加入docker组否则每次都要sudosudo usermod -aG docker $USER newgrp docker # 立即生效Docker Compose现在推荐用v2版本和旧版命令略有不同。我实测在Ubuntu 22.04上这样装最稳mkdir -p ~/.docker/cli-plugins curl -SL https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose chmod x ~/.docker/cli-plugins/docker-compose验证安装是否成功时别用老教程里的docker-compose --versionv2版命令已经变成docker compose version2. 服务端部署实战2.1 获取配置文件的小技巧官方提供的docker-compose.yml文件其实有三个版本新手建议用带mysql的完整版wget https://raw.githubusercontent.com/OpenSPG/openspg/master/dev/release/docker-compose.mysql.yml -O docker-compose.yml如果下载慢可以换成国内镜像wget https://gitee.com/OpenSPG/openspg/raw/master/dev/release/docker-compose.mysql.yml -O docker-compose.yml2.2 启动服务的隐藏参数直接up -d启动可能会遇到端口冲突我习惯先修改默认端口# 修改docker-compose.yml中的这些配置 ports: - 8887:8887 # 原8888改8887 - 50051:50051启动时加个--build参数强制重建镜像更保险docker compose up -d --build查看日志时别用logs命令这样看更清晰docker compose logs -f --tail100 openspg-server3. 客户端配置全解析3.1 镜像拉取避坑指南官方镜像默认是linux/amd64架构M1/M2芯片的Mac用户要加参数docker pull --platform linux/amd64 openspg/openspg-python:latest国内用户推荐配置镜像加速// 在/etc/docker/daemon.json中加入 { registry-mirrors: [https://registry.cn-hangzhou.aliyuncs.com] }3.2 源码关联的实用技巧克隆源码时建议指定分支避免版本不匹配git clone -b v0.1.0 https://github.com/OpenSPG/openspg启动容器时推荐用这个命令实测最稳定docker run --rm --nethost -v $(pwd)/openspg:/code \ -v ~/.m2:/root/.m2 \ # 缓存maven包 -it openspg/openspg-python:latest \ /bin/bash4. 验证与调试实战4.1 服务健康检查用curl测试服务是否正常curl http://localhost:8887/health正常会返回{status:UP}更专业的检查方式是访问swagger文档http://localhost:8887/swagger-ui.html4.2 案例运行常见问题运行riskmining案例时如果报错No module named knext需要先安装pip install -e /code/python/knext遇到schema提交失败时检查日志中的错误信息docker compose exec openspg-server tail -f logs/openspg.log5. 进阶配置技巧5.1 数据持久化方案默认配置重启后数据会丢失建议挂载mysql数据卷# 在docker-compose.yml中添加 volumes: mysql_data: driver: local5.2 性能调优参数调整JVM内存设置可以提升服务性能environment: - JAVA_OPTS-Xms4g -Xmx4g对于生产环境建议配置nginx反向代理location / { proxy_pass http://openspg-server:8887; proxy_set_header Host $host; }6. 开发环境集成6.1 IDE调试配置在VSCode中配置远程开发环境{ name: OpenSPG Container, dockerComposeFile: docker-compose.yml, service: openspg-server, workspaceFolder: /workspace }6.2 客户端SDK安装本地开发建议安装Python SDKpip install openspg-knext --extra-index-url https://pypi.python.org/simple/在PyCharm中配置解释器路径/usr/local/bin/python3