server-core/serverrun/README.md

serverrun —— 运行环境与部署编排

本目录是 server-core 的运行环境中心：集中基础设施编排（MySQL/Redis/EMQX）与三服务容器编排（部署入口）。 不存放业务代码；运行时数据全部落在各项目 serverdata/（见下方「数据策略」）。

编排总览

编排	用途	说明
mysql/docker-compose.yml	基础设施：MySQL 8	容器名 opc-mysql，宿主机端口 8091，数据 serverdata/mysql-data
redis/docker-compose.yml	基础设施：Redis 7	容器名 opc-redis，宿主机端口 8092，数据 serverdata/redis-data
mqtt/docker-compose.yml	基础设施：EMQX	容器名 opc-emqx，1883/8883/8083/8084/18083，数据 serverdata/emqx-data、emqx-log
docker-compose.yml	业务主编排：三服务一起（opc-server/opc-im/opc-compute）	部署入口，仅 8090 对外
all/docker-compose.yml	三服务一起（等价根编排，单源 include）	与根文件同效果
core/docker-compose.yml	单独启动 opc-server	只起核心服务
im/docker-compose.yml	单独启动 opc-im	只起即时通讯
compute/docker-compose.yml	单独启动 opc-compute	只起算力服务

所有编排共用外部网络 opc-network；业务与基础设施在同一网络内以容器名互访。 旧 start.sh/start-all.sh 等启动脚本与旧 Dockerfile 已废弃移除，镜像入口直接 uvicorn。

快速开始

1. 创建共享网络（一次性）

docker network create opc-network

2. 启动基础设施（MySQL / Redis / EMQX）

cd serverrun/mysql && docker compose up -d      # opc-mysql
cd serverrun/redis && docker compose up -d      # opc-redis
cd serverrun/mqtt  && docker compose up -d      # opc-emqx

镜像均走国内加速（docker.m.daocloud.io）；MySQL 首次启动由 init.sql 自动建库。

3. 构建业务镜像（各自项目内）

cd server-core && docker build -t opc-server:latest .
cd im-service  && docker build -t opc-im:latest .
cd compute     && docker build -t opc-compute:latest .

4. 配置环境变量并启动业务

cd serverrun
cp .env.example .env      # 默认已适配本地 Docker 基础设施（opc-mysql/opc-redis/opc-emqx）
docker compose up -d      # 三服务一起；或 cd all 同样效果
# 单独启动某个：cd core && docker compose up -d（im / compute 同理）

5. 数据库迁移（首次部署，幂等）

# server-core：alembic 迁移
cd serverrun && docker compose run --rm opc-server uv run alembic upgrade head

# compute：迁移 + 种子（非运行态，先于启动）
docker compose run --rm opc-compute sh -c "uv run python scripts/db/migrate.py && uv run python scripts/db/seed.py"

# im-service：无迁移脚本（lifespan 启动时建表），无需执行

6. 验证

curl http://localhost:8090/health     # opc-server 健康检查
docker compose ps                     # 业务容器状态（healthy）
docker ps | grep opc-                 # 全部容器（含基础设施）

端口与网络

服务	容器名	端口	对外	说明
opc-server	opc-server	8090	✅ 8090:8090	主 API / admin / website / 桌面更新源
opc-im	opc-im	8101	❌	即时通讯，server-core 经 http://opc-im:8101 调用
opc-compute	opc-compute	3000	❌	算力中转/计量，server-core 经 http://opc-compute:3000 调用
opc-mysql	opc-mysql	8091→3306	宿主机 8091	业务主库（opc 库、compute 库）
opc-redis	opc-redis	8092→6379	宿主机 8092	会话/缓存/限流
opc-emqx	opc-emqx	1883/8083/18083…	宿主机同端口	MQTT 总线 / WebSocket / Dashboard

业务容器内访问基础设施用 容器名 + 内部端口（.env 已默认配置）： opc-mysql:3306、opc-redis:6379、opc-emqx:1883。

服务间地址（.env 注入 server-core）：

变量	值
PINEAGENTS_COMPUTE_BASE_URL	http://opc-compute:3000
PINEAGENTS_IM_BASE_URL	http://opc-im:8101
PINEAGENTS_IM_WS_URL	ws://opc-im:8101/ws

数据策略

数据目录在各自项目的 serverdata/，挂载到容器内 /app/serverdata：

服务	宿主机目录	容器内
opc-server	../serverdata（server-core/serverdata）	/app/serverdata
opc-server 上传	../uploads（server-core/uploads）	/app/uploads
opc-im	../../im-service/serverdata	/app/serverdata
opc-compute	../../compute/serverdata	/app/serverdata
MySQL	serverdata/mysql-data	/var/lib/mysql
Redis	serverdata/redis-data	/data
EMQX	serverdata/emqx-data、emqx-log	/opt/emqx/data、/opt/emqx/log

serverdata/seed/、serverdata/prompts/ 等模板直接在宿主机（git 管理），修改后重启服务即生效； 备份覆盖 serverdata/（含 keys/、uploads/、data/）与 server-core/uploads/。

常见问题

连不上 MySQL / Redis / MQTT？ 先确认基础设施已启动（docker ps | grep opc-）；业务容器与基础设施必须在同一网络 （docker network create opc-network 后分别 up，勿用默认网络）。

升级某个服务？

cd compute && docker build -t opc-compute:latest .
cd ../serverrun && docker compose up -d opc-compute

桌面端自动更新不生效？ 确认 DESKTOP_UPDATER_PUBKEY 与 agent-desktop/mykey/tauri-signer.key 公钥一致， PUBLIC_BASE_URL 公网可访问；更新包经 opc-server /uploads 分发。

从旧的"三服务合一镜像"迁移？ 合一方案（旧 deploy/Dockerfile/entrypoint.sh）已废弃。注意：.env 中服务间地址改为 服务名（模板已默认）；IM_HOST 由 127.0.0.1 改为 0.0.0.0；旧 deploy/data/server-core 数据可复制到 serverdata/（结构一致）；首次启动前执行数据库迁移。

数据库迁移说明

镜像容器启动仅运行单进程（uvicorn），不在启动脚本内跑迁移； alembic upgrade head 与 compute migrate.py/seed.py 按上文「快速开始」显式执行（幂等）。