285 lines
6.6 KiB
Markdown
285 lines
6.6 KiB
Markdown
# 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`。
|
||
|