# 部署与本地开发

有两条路，按你要做的事选：

| 你要做的 | 走哪条 | 需要 Rust 工具链 |
|---|---|---|
| 部署一套能用的服务端 | [容器化部署](#容器化部署一条命令) | 否 |
| 改服务端代码、调试 | [源码启动](#源码启动开发用) | 是 |

## 容器化部署（一条命令）

整套 IM 核心（15 个服务）连同基础设施一起起来，不需要本机装 Rust。

```bash
cd flare-im-core
cp deploy/.env.example deploy/.env
# 至少填上 FLARE_TOKEN_SECRET，见下方「必须自己填的那一项」

docker compose --env-file deploy/.env \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.stack.yml \
  -f deploy/docker-compose.build.yml up -d
```

三个文件各管一段，分开是为了能单独用：

- `docker-compose.yml` —— 基础设施（Consul / PostgreSQL / Redis / NATS / Kafka /
  对象存储 / 可观测栈）。只想起中间件、服务跑在本机时单独用它。
- `docker-compose.stack.yml` —— 15 个 Flare 服务。**一个镜像装全部服务**，
  它们只差跑哪个二进制，拆 15 个镜像会让 registry 体积和版本偏斜翻倍。
- `docker-compose.build.yml` —— 本地构建镜像。有预构建镜像可拉时去掉这一层，
  改用 `FLARE_IMAGE=<你的镜像>`。首次本地构建约 10 分钟。

### 必须自己填的那一项

`FLARE_TOKEN_SECRET` **没有默认值**，不填直接启动失败。这不是麻烦：

> 发一个默认签名密钥等于发一个漏洞——任何拿到它的人都能伪造任意用户身份，
> 而且**完全没有症状**：服务正常启动、登录正常、日志干净。

生成一个：

```bash
openssl rand -base64 48 | tr -d '\n' | head -c 64
```

业务服务端要用**同一个**密钥：业务侧签发 IM 连接令牌、核心网关验签，
两边不一致的表现是「登录成功但 IM 连不上」。

### 改账号密码

全部在 `deploy/.env` 里，不用动任何 yml：

```bash
POSTGRES_USER=flare
POSTGRES_PASSWORD=改成你的
POSTGRES_DB=flare2
REDIS_PASSWORD=            # 留空 = 不启用认证（本地默认）
RUSTFS_ACCESS_KEY=...
RUSTFS_SECRET_KEY=...
GRAFANA_ADMIN_PASSWORD=...
```

密码里带 `@ : /` 或空格时，compose 拼不出合法的连接 URL（它不做百分号转义），
这时直接给整条：

```bash
DATABASE_URL=postgres://user:p%40ss@postgres:5432/flare2
```

### 业务服务端（可选）

社交业务的七个服务叠加在同一套基础设施上，共用同一份 `.env`：

```bash
docker compose --env-file deploy/.env \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.stack.yml \
  -f ../flare-social/deploy/docker-compose.social.yml up -d
```

建库是自动的，且**分得清全新部署与升级**：社交表不存在时执行 `init.sql`，
已存在时只补增量迁移。这个区分是必需的——`init.sql` 是重置脚本（37 条
`DROP TABLE ... CASCADE`），在有数据的库上重跑就是清空。

## 源码启动（开发用）

要改服务端代码就走这条，需要 Rust 1.94+。

```bash
cd flare-im-core/deploy
docker compose up -d        # 只起基础设施
```

具体服务名与端口以 `deploy/README.md` 为准。

## 启动脚本

```bash
cd flare-im-core
./scripts/start_server.sh    # 或 start_multi_gateway.sh
./scripts/stop_server.sh
```

常见端口（开发）：

| 服务 | 端口 |
|------|------|
| access-gateway | **60051** (WS/QUIC) |
| 其他实例 | 见 `scripts/README.md` |

## 验证

```bash
# 网关监听
lsof -i :60051

# SDK 示例（需 NEGOTIATION_HOST）
cd flare-im-core-sdk
FLARE_IM_SERVER_URL=ws://localhost:60051 cargo run --example complete_client
```

## 配置

- Hook：`flare-im-core/config/hooks.toml`（参考 `hooks.example.toml`）
- 业务样例：[integration hooks.social.example.toml](../integration/hooks.social.example.toml)

## 生产注意

- 接入层多副本 + 负载均衡（粘性会话或统一 route）
- JetStream 集群与 PostgreSQL 高可用
- 监控：Prometheus 指标 + 分布式追踪（按部署接入）

## 下一步

- [客户端接入](./05-client-connection.md)
- [架构](./01-architecture.md)