IM-web-new/WEB_DEPLOYMENT.md

# Web 版部署说明

本文档说明 `jc-web-im` 的生产部署方式。当前 Web 版由两部分组成：

- Vue 构建后的静态文件，部署到 Web 根目录。
- `dist/api/*.php` PHP 代理接口，负责安全调用本机 `im-server` / `app-server` 相关接口。

浏览器不能直接携带 `im-server` admin secret 访问 `18080`，所以联系人列表、备注名修改、消息发送等功能通过 PHP 代理完成。

## 目录

```text
/var/www/jc-im/jc-web-im
├── public/api/              # PHP 代理源码，构建时复制到 dist/api
├── public/config/           # 运行时配置
├── src/                     # Vue 前端源码
├── deploy/                  # Nginx 示例配置
└── dist/                    # npm run build 后的生产目录
```

生产环境建议让 Nginx 的 `root` 指向：

```text
/var/www/jc-im/jc-web-im/dist
```

## 依赖

服务器需要安装：

- Nginx
- PHP-FPM
- PHP 扩展：`curl`、`mbstring`
- Node.js / npm，仅构建时需要

PHP 版本：

- 最低建议：PHP 7.4
- 推荐：PHP 8.1 / 8.2 / 8.3

当前 PHP 代理代码使用 `curl_*`、`random_int`、`Throwable`、`mb_strlen` 等能力，部署前请确认 `curl` 和 `mbstring` 扩展可用。

## 后端服务要求

Web 版依赖以下服务正常运行：

```text
app-server: http://127.0.0.1:18888
im-server HTTP/API: http://127.0.0.1:18000
im-server admin: http://127.0.0.1:18080
```

`im-server admin`、IM 数据库和应用数据库配置通过 PHP-FPM 环境变量提供：

```text
public/api/im_web_bootstrap.php
```

需要配置：

```text
IM_ADMIN_URL=http://127.0.0.1:18080
IM_ADMIN_SECRET=请填写管理端密钥
IM_DB_DSN=mysql:host=127.0.0.1;port=3306;dbname=wfchat;charset=utf8mb4
IM_DB_USER=请填写数据库用户
IM_DB_PASSWORD=请填写数据库密码
IM_APP_DB_DSN=mysql:host=127.0.0.1;port=3306;dbname=appdata;charset=utf8mb4
IM_APP_DB_USER=请填写应用数据库用户
IM_APP_DB_PASSWORD=请填写应用数据库密码
IM_DB_TIMEZONE=Asia/Bangkok
```

请在 PHP-FPM pool、容器 secret 或部署平台的环境变量中配置，禁止把真实密钥提交到仓库。

## 构建

在项目目录执行：

```bash
cd /var/www/jc-im/jc-web-im
npm run build
```

构建完成后，生产文件位于：

```text
/var/www/jc-im/jc-web-im/dist
```

## 运行时配置

运行时配置文件：

```text
dist/config/runtime-config.js
```

示例：

```js
window.JC_WEB_IM_CONFIG = {
  appServer: 'http://your-domain:18888',
  registerConfigApi: 'http://your-domain:8024/api/register-config',
  imServerHost: 'your-domain',
  imRoutePort: 18000,
  useWss: false,
  wsPath: '/ws',
  sdkMode: 'custom-ws'
};
```

常用字段说明：

| 字段 | 说明 |
| --- | --- |
| `appServer` | Web 登录、验证码等 App Server 地址 |
| `registerConfigApi` | 注册配置接口地址 |
| `imServerHost` | IM HTTP/API 和 WebSocket 使用的主机名 |
| `imRoutePort` | IM route/API 端口，当前为 `18000` |
| `useWss` | 是否使用 WSS |
| `wsPath` | WebSocket 路径 |
| `sdkMode` | 当前使用 `custom-ws` |

联系人相关 PHP 代理默认使用同源地址：

```text
/api/contacts.php
/api/update_alias.php
/api/add_contact.php
/api/send_message.php
/api/messages.php
```

通常不需要在 `runtime-config.js` 里单独配置这些地址。

## Nginx 示例

根据实际 PHP-FPM socket 调整 `fastcgi_pass`，例如 PHP 8.3：

```nginx
server {
    listen 8023;
    listen [::]:8023;
    server_name your-domain _;

    root /var/www/jc-im/jc-web-im/dist;
    index index.html;
    client_max_body_size 100m;

    location = / {
        try_files /index.html =404;
        expires -1;
        add_header Cache-Control "no-store";
    }

    location = /index.html {
        expires -1;
        add_header Cache-Control "no-store";
    }

    location = /config/runtime-config.js {
        expires -1;
        add_header Cache-Control "no-store";
    }

    location ~ ^/api/.+\.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_param PHP_ADMIN_VALUE "open_basedir=/var/www/jc-im/jc-web-im/dist/:/tmp/";
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        expires -1;
        add_header Cache-Control "no-store";
    }

    location / {
        etag on;
        try_files $uri $uri/ /index.html;
        expires 12h;
    }
}
```

启用配置后检查并重载：

```bash
sudo nginx -t
sudo systemctl reload nginx
```

## 防火墙建议

生产环境建议：

- 对外开放 Web 端口，例如 `80` / `443` / `8023`。
- `18888` 如需浏览器直接访问 app-server，需要对外开放。
- `18000` 如 WebSocket/route 需要浏览器直连，需要对外开放。
- `18080` admin 端口不要对公网开放，只允许本机 PHP 代理访问。

## 验证

检查 PHP 语法：

```bash
php -l /var/www/jc-im/jc-web-im/dist/api/contacts.php
php -l /var/www/jc-im/jc-web-im/dist/api/update_alias.php
```

检查 Web 页面：

```bash
curl -I http://127.0.0.1:8023/
```

检查联系人接口：

```bash
curl -s -H 'Content-Type: application/json' \
  --data '{"userId":"你的用户ID"}' \
  http://127.0.0.1:8023/api/contacts.php
```

成功时返回：

```json
{
  "code": 0,
  "message": "success",
  "result": {
    "contacts": []
  }
}
```

检查备注名修改接口：

```bash
curl -s -H 'Content-Type: application/json' \
  --data '{"userId":"你的用户ID","targetId":"联系人ID","alias":"测试备注"}' \
  http://127.0.0.1:8023/api/update_alias.php
```

成功时返回：

```json
{
  "code": 0,
  "message": "success",
  "result": {
    "contact": {
      "uid": "联系人ID",
      "alias": "测试备注"
    }
  }
}
```

## 常见问题

### 页面能打开，但联系人加载失败

优先检查：

- PHP-FPM 是否运行。
- Nginx 的 PHP location 是否命中 `/api/*.php`。
- `curl` 扩展是否启用。
- `public/api/im_web_bootstrap.php` 中 `IM_ADMIN_URL` 和 `IM_ADMIN_SECRET` 是否匹配当前 `im-server`。
- `im-server` 的 `18080` admin 接口是否在本机可访问。

### 修改备注名无效

检查：

- `dist/api/update_alias.php` 是否存在。
- Nginx 是否允许执行 `dist/api/*.php`。
- `im-server` 是否提供 `/admin/friend/set_alias`。
- 当前登录用户和目标联系人是否确实是好友关系。

### 部署后仍是旧前端

检查：

- Nginx `root` 是否指向新的 `dist` 目录。
- 是否执行过 `npm run build`。
- 浏览器是否缓存了旧资源。`index.html` 和 `runtime-config.js` 应配置为 `no-store`。