# begin_im

**Repository Path**: yangsj/begin_im

## Basic Information

- **Project Name**: begin_im
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Begin IM

Java 8 桌面 IM，服务端使用 Netty，客户端使用 JavaFX、OkHttp WebSocket 和 SQLite。

当前实现支持：

- Gateway 从外部配置读取固定 ID，并注册到 MySQL 集群注册表。
- 每个 Gateway 内嵌 GatewayCenter，无独立 Center 服务。
- 客户端通过 `/v1/gateways` 获取 60 秒有效节点列表，并从低负载节点中加权选择。
- 同 Gateway 本地直推，跨 Gateway 通过复用的 Netty Peer Channel 转发。
- 用户路由和离线消息使用 MySQL，在线消息正文不经过 MySQL。
- 离线消息登录重放，客户端写入 SQLite 后返回 `DELIVERED_ACK`。

## Modules

| 模块 | 职责 |
|---|---|
| `im-common` | IM 协议、Gateway 发现 DTO、JSON 编解码 |
| `im-server-netty` | WebSocket Gateway、内嵌 GatewayCenter、MySQL Adapter、Peer Transport |
| `im-client-javafx` | 桌面 UI、Gateway 发现和选点、WebSocket、SQLite 本地消息 |

## Requirements

- JDK 8
- Maven 3.6+
- MySQL 8.x

## Build

```bash
mvn clean package
```

## MySQL

首次创建数据库：

```sql
CREATE DATABASE IF NOT EXISTS begin_im
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;
```

Gateway 启动时会自动创建 `gateway_node`、`user_route` 和 `offline_message` 表。

## Start Gateway

先为每台 Gateway 配置唯一且稳定的 ID：

```properties
# config/gateway.properties
gateway.id=gw-local-01
gateway.cluster-id=begin-im-local
```

```bash
export BEGIN_IM_DB_USER=root
export BEGIN_IM_DB_PASSWORD='your-password'
java -jar im-server-netty/target/im-server-netty-0.1.0-SNAPSHOT.jar
```

默认地址：

```text
WebSocket:  ws://127.0.0.1:8088/im
Discovery:  http://127.0.0.1:8088/v1/gateways
Health:     http://127.0.0.1:8088/health
Peer:       127.0.0.1:9088
```

常用环境变量：

| 环境变量 | 默认值 |
|---|---|
| `BEGIN_IM_CONFIG` | `config/gateway.properties` |
| `BEGIN_IM_PORT` | `8088` |
| `BEGIN_IM_INTERNAL_PORT` | 公开端口加 `1000` |
| `BEGIN_IM_PUBLIC_HOST` | `127.0.0.1` |
| `BEGIN_IM_INTERNAL_HOST` | `127.0.0.1` |
| `BEGIN_IM_DB_URL` | 本机 `begin_im` 数据库 |
| `BEGIN_IM_DB_USER` | `root` |
| `BEGIN_IM_DB_PASSWORD` | 空 |

也可以使用 JVM 参数指定另一份配置文件：

```bash
java -Dbegin.im.config=/etc/begin-im/gateway.properties \
  -jar im-server-netty/target/im-server-netty-0.1.0-SNAPSHOT.jar
```

`gateway.id` 只从配置文件读取，格式为 `[A-Za-z0-9._-]{1,128}`。同一 `gateway.cluster-id` 下如果已经存在租约未过期的同名节点，新进程会在开放端口前终止启动。

## Logs

服务端和客户端均使用 SLF4J + Logback，日志按小时生成文件，默认保留 168 小时：

```text
~/.begin-im/logs/server/begin-im-server.yyyy-MM-dd_HH.log
~/.begin-im/logs/client/begin-im-client.yyyy-MM-dd_HH.log
```

可以通过 JVM 参数修改日志目录：

```bash
java -Dbegin.im.log.dir=/data/begin-im/logs -jar ...
```

INFO 记录启动、入群、拓扑、Peer 连接、用户登录和客户端重连；逐消息路由及送达确认使用 DEBUG。日志不会记录消息正文、数据库密码或 Token。

## Start Client

```bash
java -jar im-client-javafx/target/im-client-javafx-0.1.0-SNAPSHOT.jar
```

登录页默认发现地址：

```text
http://localhost:8088/v1/gateways
```

仍兼容直接输入 `ws://host:port/im`。客户端配置保存在 `~/.begin-im/client.properties`，消息保存在 `~/.begin-im/{userId}.db`。

## Verification

```bash
mvn test
```

Gateway 运行时可执行端到端离线消息测试：

```bash
mvn -pl im-client-javafx -am \
  -Dbegin.im.integration=true \
  -Dtest=GatewayRuntimeIntegrationTest \
  -Dsurefire.failIfNoSpecifiedTests=false test
```

完整设计见 [GatewayCenter 与 Gateway 集群设计](docs/gateway-center-cluster-design.md)。

服务端生产配置、systemd、Nginx 和故障处理见 [服务端配置部署启动指南](docs/server-configuration-deployment-guide.md)。

## Current Limits

- 当前是单设备路由，同一用户新登录会替换旧连接。
- 文件二进制、群聊、端到端加密和多区域 Router 尚未实现。
- Direct Peer Transport 面向小型 Gateway 集群；达到容量阈值后切换 `RouterClusterTransport`。