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. 创建共享网络（一次性）

```bash
docker network create opc-network
```

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

```bash
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. 构建业务镜像（各自项目内）

```bash
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. 配置环境变量并启动业务

```bash
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. 数据库迁移（首次部署，幂等）

```bash
# 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. 验证

```bash
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`，勿用默认网络）。

**升级某个服务？**
```bash
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` 按上文「快速开始」显式执行（幂等）。