系统部署手册

一个进程同时提供 HTTP 与 WebSocket。Markdown 原文见仓库 docs/部署手册.md。PHP 目录仅作参考，不要部署 PHP。

健康检查 GET /api/health。开发 Swagger：/swagger。

1. 架构与端口

浏览器 / 嵌入 JS
    ├─ http(s)://域名/     →  Nginx :80/:443  →  应用 :8000
    └─ ws(s)://域名/ws     →  Nginx /ws       →  应用 :5017

• 正式站 / HTTPS / 反代 80：前端连 wss(s)://当前访问域名/ws（跟页面同源），由 Nginx 把 /ws 转到应用 5017。
• 仅本地拆端口（页面在 :8000）：连 ws://主机名:5017/ws。生产务必配置 Nginx location /ws 的 Upgrade，否则会话会提示「请先登录」。

2. 环境要求

出厂默认密码 123456。JWT、短信、邮件写在 config.yaml 的 uchat 段，不要把开发机密钥带上生产。

3. 配置文件

必须改：uchat.jwt.secret、MySQL link、webDomain。短信/邮件用不到可留空。跨网语音再填 TURN。

使用现有 PHP 库或导入 mysqldump。程序会自动补验证码日志、知识库向量等可选表。

4. 二进制部署

工作目录要能读到 manifest/config/ 和 resource/public/。

本机开发

gf run main.go
# PowerShell 内存紧张时
$env:GOMAXPROCS='1'; go build -p 1 -o uchat.exe .
.\uchat.exe

Linux

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -p 1 -trimpath -ldflags="-s -w" -o uchat .
# 上传到 /opt/uchat/（二进制 + manifest/config + resource/public）
cd /opt/uchat && ./uchat

systemd 工作目录设为程序目录，After=mysql redis，LimitNOFILE=65535。完整 unit 见仓库 Markdown。

5. Docker 部署

仓库含 Dockerfile、docker-compose.yml（MySQL + Redis + 应用 + Nginx）。

1. 导出现有库到 docker/init/01-uchat.sql（镜像不内置全量表；仅数据卷为空时自动导入）。
2. 复制 .env.example 为 .env（PowerShell：Copy-Item .env.example .env），改密码；改 docker/config/config.yaml 的 JWT。
3. 启动：

docker compose up -d --build
docker compose ps
docker compose logs -f app

• 站点 http://服务器:8000/ 或 Nginx http://服务器/
• 健康检查 /api/health
• WebSocket ws://服务器:5017/ws

已有 MySQL 卷时 init 不会再跑，改为 docker compose exec -T mysql mysql -uuchat -puchat uchat < docker/init/01-uchat.sql。

连宿主机库：MYSQL_HOST=host.docker.internal（Linux 可加 extra_hosts: host.docker.internal:host-gateway）。

多实例共用同一 Redis 与 MySQL。实时消息走频道 uchat:hub。HTTP 无需粘滞；WS 停在某一进程，靠 Redis 广播。

docker compose down       # 保留数据卷
docker compose down -v    # 清空库和上传，不可恢复

6. Nginx 反代

站点转到 :8000，/ws 转到 :5017，并开启 WebSocket Upgrade。完整配置见仓库 docker/nginx.conf。HTTPS 示例 docker/nginx-ssl.conf.example。

语音通话需要 HTTPS。商户「接入域名」把 DNS 指到本机，server_name 写该域名，每个域名只能绑一个商户。

7. 上线检查

1. GET /api/health 为 ok。
2. /admin/ 能出验证码并登录。
3. 浏览器 Network 里能看到 /ws 连接。
4. 客服上线后，/chat/?m=商户编码 能发消息。
5. 上传图片后 URL 可打开。
6. 生产改 JWT、默认密码；按需关商户自助注册。

8. 备份与升级

备份 MySQL、resource/public/storage/（或卷 upload_data）、manifest/config/。升级只替换二进制或重新 compose build，保留配置与数据卷，不要 down -v。

9. 排障