# xim.bchongw.com 部署记录

部署日期：2026-09-02  
目标服务器：`8.219.70.152`  
运行方式：既有宝塔 Linux 面板 + 宝塔 Go 项目 + 既有 MySQL 5.7（非 Docker）

## 对外地址

- 管理端：`https://xim.bchongw.com/admin/`
- API：`https://xim.bchongw.com`
- 健康检查：`https://xim.bchongw.com/healthz`
- WebSocket：`wss://xim.bchongw.com/ws`
- 管理 API：`https://xim.bchongw.com/admin/v1`

HTTP 已强制 301 跳转到 HTTPS。Let's Encrypt 证书由宝塔托管，证书到期时间为 2026-12-01，宝塔中的“续签 Let's Encrypt 证书”计划任务处于启用状态。

## 宝塔与服务

目标机原本已经安装并运行宝塔、Nginx 1.26.1 和 MySQL 5.7.40，因此没有重装面板或替换现有 Web/数据库环境。原有网站和数据库均未修改。

| 项目 | 值 |
| --- | --- |
| 宝塔 Go 项目 | `xim_im` |
| Go 运行用户 | `www` |
| Go 监听地址 | `127.0.0.1:18888` |
| Go 当前版本 | `/www/server/xim-im/releases/20260902-100344` |
| Go 当前入口 | `/www/server/xim-im/current` |
| Go 环境文件 | `/etc/xim-im.env`（`root:www 0640`） |
| Go 日志 | `/www/wwwlogs/go/xim_im.log` |
| 上传目录 | `/www/wwwroot/xim-data/uploads` |
| 管理端当前版本 | `/www/wwwroot/xim-admin/releases/20260902-100344` |
| 管理端入口 | `/www/wwwroot/xim.bchongw.com/admin` |
| Nginx 主配置 | `/www/server/panel/vhost/nginx/go_xim_im.conf` |
| Nginx 扩展路由 | `/www/server/panel/vhost/nginx/extension/xim_im/xim_routes.conf` |
| 运维脚本 | `/www/server/xim-im/ops`（仅 root 可访问） |
| 初始管理员凭据 | `/root/.xim-initial-credentials`（`root:root 0600`） |

后端只监听回环地址，公网不开放 18888；MySQL 继续使用服务器既有实例，没有新增公网端口。

## 数据库

- 宝塔数据库名：`xim`
- 应用账号：`xim_app`，仅授予 `xim` 库权限
- 字符集：`utf8mb4`
- 已执行迁移：`001_users.sql` 至 `029_admin_create_users.sql`，共 29 条
- 当前业务表：66 张
- 演示数据：关闭
- 初始有效管理员：1 个

数据库密码、JWT 密钥和配置加密密钥均在目标服务器上随机生成，没有写入工作区或本记录。

## 发布产物

- 后端 Linux/amd64 静态二进制 SHA-256：`76ee90fc9ddf4ff5472d20e7595c4e9380b0fee4a4b972aa30c089a03903abe8`
- 完整部署包 SHA-256：`49814e881cc2e1776dd768316a37509269ab13a78d8960a9e1c278bcb15f4e87`
- 服务器归档：`/www/server/xim-im/releases/20260902-100344/deployment-bundle.zip`
- 面板数据库部署前备份：`/www/backup/xim-initial-20260902-100344`
- 管理 API 路由修复前备份：`/www/backup/xim-initial-20260902-100344/xim_routes.before-api-fix.conf`

本地构建前执行了后端 `go test ./...`、管理端类型检查和管理端生产构建，全部通过。

## 安全处理

- `IM_ALLOWED_ORIGINS` 仅允许 `https://xim.bchongw.com`。
- 管理端运行时接口地址使用同域 `/admin/v1`。
- 初始管理员创建后，`IM_BOOTSTRAP_ADMIN_PASSWORD` 已从运行环境清空；凭据只保存在 root 专用文件。
- 管理端入口 HTML 和 `_app.config.js` 禁止缓存；散列静态资源使用长期缓存。
- 网关传递 `X-Forwarded-Proto`，上传文件生成的公开地址使用 HTTPS。
- 未认证管理接口和 WebSocket 握手均返回 401。

## 验收结果

- DNS 公网 A 记录解析为 `8.219.70.152`。
- Nginx 配置检查通过。
- TLS 1.3 握手和证书域名校验通过。
- `http://xim.bchongw.com/healthz` 返回 301，并跳转到 HTTPS。
- `https://xim.bchongw.com/healthz` 返回 200 和 `status=ok`。
- `https://xim.bchongw.com/admin/` 返回 200。
- 管理端运行时配置指向 `/admin/v1`。
- 使用初始管理员完成真实登录、用户信息、17 项权限码、仪表盘及退出登录验收。
- 宝塔 `xim_im` 项目重启后 PID 更新，服务和公网 HTTPS 健康检查恢复正常。
- 宝塔数据库列表存在 `xim`，Go 项目已设置开机启动和守护。
- 测试产生的未退出管理会话已撤销。

## 运维入口

在宝塔中进入“网站 → Go 项目 → `xim_im`”进行启动、停止、重启和日志查看；在“数据库 → MySQL → `xim`”管理项目数据库。

常用检查：

```bash
curl -fsS http://127.0.0.1:18888/healthz
curl -fsS https://xim.bchongw.com/healthz
/www/server/nginx/sbin/nginx -t
tail -n 200 /www/wwwlogs/go/xim_im.log
```

首次登录后应在管理端修改管理员密码。短信、对象存储、第三方登录和正式支付渠道仍需在管理端填入实际厂商参数并分别完成联调；本次没有写入任何真实第三方密钥。

## 2026-09-03 语音上传兼容修复（10:21）

已同步发布与 `im.bchongw.com` 完全相同的后端二进制。服务端新增对无 ID3 标签、直接以 MPEG 音频帧开头的 MP3 录音识别，并兼容客户端显式传入 `purpose=voice`；原有媒体上传接口与鉴权规则不变。

- 当前版本：`/www/server/xim-im/releases/voice-upload-20260903-102059`，`/www/server/xim-im/current` 已原子切换至该目录。
- 回滚备份：`/www/backup/xim-voice-upload-20260903-102059`；上一版本目录 `/www/server/xim-im/releases/20260903-090411` 继续保留。
- 新后端 SHA-256：`ac1b0c9f5a48b2386fbecb604003fc97299951e580c97e02f8765e1e0228deee`。
- 上一后端 SHA-256：`b250dd522a74a8812d392e5ed3ae17b2981c799978abf402770dfff1c7442086`。
- 源码归档 SHA-256：`0dbc6fd23c2bd8e69cc0a15e21d3b1f5b60e7586c91dd20ef486a46071ad047b`。
- 本次没有数据库迁移、业务数据写入、Nginx 改动或管理端目录切换。

发布前完整执行 `go test ./...`。发布后宝塔 Go 项目 PID 为 `1523690`，磁盘文件与 `/proc` 运行映像摘要均为新版本；本机和公网健康检查返回 200，未认证媒体上传请求返回 401。两台接口服务器的运行二进制摘要一致。

## 2026-09-03 聊天媒体查询修复（11:50）

管理端“聊天媒体”页面已发布，但数据库漏执行 `033_chat_media_management.sql`，导致列表接口查询不存在的 `im_message_media` 表并返回“查询聊天媒体失败”。本次先完成整库 gzip 备份，再补执行该迁移。

- 数据库备份：`/www/backup/xim-chat-media-migration-20260903-115006/xim.sql.gz`，备份目录权限 0700、文件权限 0600，gzip 完整性检查通过。
- 迁移：`033_chat_media_management.sql`，SHA-256 `677c8dfe790e5996326f29967e41dba1f6a2a8018112be7eb42dc9fab1c600df`；迁移记录与工作区文件校验值一致。
- 6 条历史图片/语音消息已全部回填至管理表，缺失 0 条；列表联表查询返回 6 条，统计查询为正常保存 6 条、已清理 0 条、清理失败 0 条，总文件大小 480098 字节。
- 自动清理保持关闭，默认保留天数为 90 天；本次未删除、覆盖或上传任何聊天文件。
- 管理端发布目录仍为 `/www/wwwroot/xim-admin/releases/20260903-112804`；后端 SHA-256 为 `5a97957780900428cc106f2140d640d2d04963729eeeefb396fc8fffc32763a4`，与主站实际运行版本一致，无需重启。
- 复核 `https://xim.bchongw.com/healthz`、管理端入口均返回 200；未登录访问聊天媒体接口返回 401，确认路由与鉴权正常。