Import JC Web IM

2026-10-09 22:49:53 +07:00
commit 3377b6072a
74 changed files with 62902 additions and 0 deletions
@@ -0,0 +1,284 @@
+# 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`。
+