# kefu 客服系统 · 本地到线上完整部署方案

> 项目：kefu · 企业级 AI 智能客服平台
> 开发团队：kefu 开发团队 zero
> 联系方式：619864585@qq.com
> 在线域名：https://kefu.xiaozhusho.top
> 文档版本：v1.0（2026-08-10）

---

## 目录

1. [部署架构概览](#一部署架构概览)
2. [环境要求](#二环境要求)
3. [本地开发环境搭建](#三本地开发环境搭建)
4. [本地项目初始化](#四本地项目初始化)
5. [数据库初始化与迁移](#五数据库初始化与迁移)
6. [代码同步与构建](#六代码同步与构建)
7. [服务器环境准备](#七服务器环境准备)
8. [生产环境部署](#八生产环境部署)
9. [Nginx 反向代理 + HTTPS](#九nginx-反向代理--https)
10. [进程守护与开机自启](#十进程守护与开机自启)
11. [DNS 域名解析](#十一dns-域名解析)
12. [上线前检查清单](#十二上线前检查清单)
13. [上线后验证](#十三上线后验证)
14. [回滚方案](#十四回滚方案)
15. [运维与监控](#十五运维与监控)
16. [常见问题 FAQ](#十六常见问题-faq)

---

## 一、部署架构概览

```
┌─────────────────────────────────────────────────────┐
│                  互联网（用户）                         │
└────────────────────┬────────────────────────────────┘
                     │ HTTPS (443)
                     ▼
        ┌──────────────────────────┐
        │   阿里云 / 腾讯云 ECS    │
        │  ┌────────────────────┐  │
        │  │   Nginx (反向代理) │  │
        │  │   + HTTPS / HTTP/2 │  │
        │  └─────────┬──────────┘  │
        │            │              │
        │  ┌─────────▼──────────┐  │
        │  │  Webman (8787)     │  │
        │  │  + Workerman       │  │
        │  └─────────┬──────────┘  │
        │            │              │
        │  ┌─────────▼──────────┐  │
        │  │  MySQL 8.0 (3306)  │  │
        │  └────────────────────┘  │
        └──────────────────────────┘
                     │
            ┌────────┴─────────┐
            ▼                  ▼
   ┌─────────────────┐  ┌──────────────┐
   │  百度千帆 App   │  │  微信开放平台 │
   │  (AI 大模型)    │  │  (公众号 / 小程序) │
   └─────────────────┘  └──────────────┘
```

---

## 二、环境要求

### 2.1 服务器最低配置

| 资源 | 最低 | 推荐 |
| --- | --- | --- |
| CPU | 1 核 | 2 核+ |
| 内存 | 1 GB | 2 GB+ |
| 磁盘 | 20 GB | 40 GB+ SSD |
| 带宽 | 1 Mbps | 5 Mbps+ |
| 操作系统 | Ubuntu 20.04 / CentOS 7+ / Windows Server 2019+ | Ubuntu 22.04 LTS |

### 2.2 软件依赖

| 软件 | 版本 | 说明 |
| --- | --- | --- |
| PHP | 8.0+ | 必需：pdo_mysql、openssl、mbstring、curl 扩展 |
| MySQL | 5.7+ / 8.0 | 主数据库 |
| Nginx | 1.18+ | 反向代理 + HTTPS |
| Composer | 2.x | PHP 包管理（部署时用） |
| Git | 2.x | 代码拉取 |
| SSL 证书 | - | 推荐 Let's Encrypt 免费证书 |

### 2.3 外部服务（可选）

| 服务 | 用途 |
| --- | --- |
| 百度智能云 - 千帆 App | AI 大模型 |
| 微信公众平台 | 公众号客服消息 |
| 微信小程序后台 | 小程序客服消息 |
| 阿里云 / 腾讯云监控 | 服务监控告警 |

---

## 三、本地开发环境搭建

### 3.1 安装 PHP（Windows）

#### 方式 A：使用 phpStudy（推荐新手）

1. 下载 [phpStudy 2018 或以上](https://www.xp.cn/)
2. 解压到 `D:\phpstudy_pro\`
3. 启动 phpStudy → 启动 Apache/Nginx + MySQL
4. 切换 PHP 版本为 8.0+
5. 验证：`cmd → php -v`

#### 方式 B：手动安装

```powershell
# 使用 chocolatey
choco install php --version=8.1
choco install mysql --version=8.0
choco install composer
choco install nginx

# 验证
php -v
mysql --version
composer --version
```

### 3.2 安装 MySQL

```powershell
# 启动 MySQL 服务
net start mysql

# 创建数据库和用户
mysql -u root -p
```

```sql
CREATE DATABASE kefu CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kefu'@'localhost' IDENTIFIED BY 'adminkefu';
GRANT ALL PRIVILEGES ON kefu.* TO 'kefu'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### 3.3 安装 Composer（部署用）

```powershell
# Windows
# 下载 https://getcomposer.org/Composer-Setup.exe 安装

# Linux / macOS
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
```

---

## 四、本地项目初始化

### 4.1 克隆代码

```bash
cd /path/to/your/webroot    # Windows: d:\phpstudy_pro\WWW
# Linux: /var/www/html
git clone https://your-git-repo/kefu.git
cd kefu
```

### 4.2 安装 PHP 依赖

```bash
cd server
composer install --no-dev --optimize-autoloader
```

### 4.3 配置环境变量

编辑 `server/.env`：

```ini
# 数据库配置
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=kefu
DB_USERNAME=kefu
DB_PASSWORD=adminkefu

# 服务监听
WS_HOST=0.0.0.0
WS_PORT=8787

# 百度千帆 AI 配置（管理后台 AI 智能体配置里填）
# 也可在管理后台 → AI 智能体 里配置
```

### 4.4 配置运行用户（Linux）

```bash
sudo chown -R www-data:www-data /var/www/html/kefu/server/runtime
sudo chmod -R 755 /var/www/html/kefu/server/runtime
sudo chmod -R 644 /var/www/html/kefu/server/.env
```

---

## 五、数据库初始化与迁移

### 5.1 首次部署：初始化数据库

```bash
cd server
mysql -u kefu -p kefu < sql/init.sql
```

**`init.sql` 会创建**：
- 47 张业务表（含多租户、用户、角色、权限、会话、消息、AI、质检、报表等）
- 默认租户 `demo`
- 默认账号：
  - 超管：`admin / admin123`
  - 客服：`agent01 / admin123`、`agent02 / admin123`

### 5.2 增量升级：执行 migration 脚本

按文件名顺序执行增量迁移脚本：

```bash
# 依次执行（按版本号排序）
mysql -u kefu -p kefu < sql/migration_features_v2.sql
mysql -u kefu -p kefu < sql/migration_features_v3.sql
mysql -u kefu -p kefu < sql/migration_ai_agent.sql
mysql -u kefu -p kefu < sql/migration_channels.sql
mysql -u kefu -p kefu < sql/migration_default_perms.sql
mysql -u kefu -p kefu < sql/migration_ticket_permission.sql
mysql -u kefu -p kefu < sql/migration_worksheet.sql
mysql -u kefu -p kefu < sql/migration_leave_message_ticket_no.php
mysql -u kefu -p kefu < sql/migration_v3.php
```

**PHP 格式的迁移脚本**（带数据迁移逻辑）：
```bash
php sql/migration_leave_message.php
php sql/migration_channels_v2.php
php sql/migration_visitor_field.php
```

### 5.3 验证数据库

```sql
SHOW TABLES;                              -- 应看到 47 张 kefu_ 开头的表
SELECT * FROM kefu_tenant;                -- 默认有 1 条记录
SELECT COUNT(*) FROM kefu_employee;       -- 默认有 3 条记录（admin + agent01 + agent02）
SELECT * FROM kefu_role;                  -- 默认有 3 条角色（admin/supervisor/agent）
SELECT * FROM kefu_permission LIMIT 10;   -- 应有菜单/API 权限
```

---

## 六、代码同步与构建

### 6.1 本地开发完成后的同步流程

```bash
# 1. 提交本地代码
cd kefu
git add .
git commit -m "feat: 新增 XX 功能"
git push origin main

# 2. 在服务器拉取最新代码
ssh root@kefu.xiaozhusho.top
cd /var/www/html/kefu
git pull origin main
```

### 6.2 部署前自检清单

```bash
# PHP 语法检查
cd /var/www/html/kefu/server
find app -name "*.php" -exec php -l {} \; | grep -v "No syntax errors"

# 检查关键文件存在
ls -la start.php .env composer.json
```

### 6.3 优化 Composer 自动加载（生产环境）

```bash
cd server
composer install --no-dev --optimize-autoloader --no-interaction
```

---

## 七、服务器环境准备

### 7.1 阿里云 ECS 初始化（Ubuntu 22.04）

```bash
# SSH 连接服务器
ssh root@your-server-ip

# 更新系统
apt update && apt upgrade -y

# 安装基础工具
apt install -y nginx mysql-server php8.1 php8.1-fpm php8.1-mysql php8.1-curl php8.1-mbstring php8.1-xml php8.1-zip php8.1-bcmath php8.1-opcache php8.1-gd unzip git curl composer

# 启动服务
systemctl enable nginx mysql php8.1-fpm
systemctl start nginx mysql php8.1-fpm
```

### 7.2 配置 MySQL（生产环境）

```bash
sudo mysql_secure_installation

# 创建 kefu 数据库
mysql -u root -p
```

```sql
CREATE DATABASE kefu CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kefu'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON kefu.* TO 'kefu'@'localhost';
FLUSH PRIVILEGES;
```

### 7.3 防火墙配置

```bash
# 仅开放必要端口
ufw allow 22/tcp     # SSH
ufw allow 80/tcp     # HTTP
ufw allow 443/tcp    # HTTPS
ufw enable

# 不要开放 8787 端口给外网（仅监听 127.0.0.1）
```

---

## 八、生产环境部署

### 8.1 上传代码

#### 方式 A：Git 拉取（推荐）

```bash
cd /var/www/html
git clone https://your-git-repo/kefu.git
cd kefu/server
composer install --no-dev --optimize-autoloader
```

#### 方式 B：SCP 上传

```powershell
# Windows 本地
scp -r C:\path\to\kefu root@your-server-ip:/var/www/html/
```

### 8.2 配置生产环境 `.env`

```bash
cd /var/www/html/kefu/server
cp .env.example .env   # 如果有
nano .env
```

```ini
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=kefu
DB_USERNAME=kefu
DB_PASSWORD=strong_password_here
WS_HOST=127.0.0.1
WS_PORT=8787
```

### 8.3 设置目录权限

```bash
cd /var/www/html/kefu
sudo chown -R www-data:www-data .
sudo find . -type d -exec chmod 755 {} \;
sudo find . -type f -exec chmod 644 {} \;
sudo chmod -R 775 server/runtime
```

### 8.4 初始化数据库（生产环境）

```bash
cd /var/www/html/kefu/server
mysql -u kefu -p kefu < sql/init.sql
```

### 8.5 启动 Webman 服务

```bash
cd /var/www/html/kefu/server
php start.php start -d    # 后台守护进程
```

### 8.6 验证服务

```bash
# 查看进程状态
php start.php status

# 查看监听端口
ss -tlnp | grep 8787

# 测试本地访问
curl -i http://127.0.0.1:8787/api/health
```

预期返回：
```json
{"code":0,"msg":"ok","data":{"status":"ok","time":"..."}}
```

---

## 九、Nginx 反向代理 + HTTPS

### 9.1 申请 SSL 证书（Let's Encrypt 免费）

```bash
# 安装 certbot
apt install -y certbot python3-certbot-nginx

# 申请证书（替换为你的域名）
certbot --nginx -d kefu.xiaozhusho.top -d www.kefu.xiaozhusho.top

# 自动续期（已自动配置）
certbot renew --dry-run
```

### 9.2 配置 Nginx

创建 `/etc/nginx/sites-available/kefu`：

```nginx
# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name kefu.xiaozhusho.top www.kefu.xiaozhusho.top;
    return 301 https://$host$request_uri;
}

# HTTPS server
server {
    listen 443 ssl http2;
    server_name kefu.xiaozhusho.top www.kefu.xiaozhusho.top;

    # SSL 证书（Let's Encrypt 自动生成）
    ssl_certificate /etc/letsencrypt/live/kefu.xiaozhusho.top/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/kefu.xiaozhusho.top/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 日志
    access_log /var/log/nginx/kefu.access.log;
    error_log /var/log/nginx/kefu.error.log;

    # 根目录
    root /var/www/html/kefu/server/public;
    index index.html;

    # 客户端请求体大小（上传文件）
    client_max_body_size 50M;

    # 静态资源直接服务（高效）
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
        expires 7d;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }

    # 默认入口（index.html 商业化首页）
    location = / {
        try_files /index.html =404;
    }

    # WebSocket 路径
    location /ws {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    # API + 所有其他请求代理到 Webman
    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}
```

### 9.3 启用配置

```bash
sudo ln -s /etc/nginx/sites-available/kefu /etc/nginx/sites-enabled/
sudo nginx -t                # 测试配置
sudo systemctl reload nginx  # 重新加载
```

### 9.4 验证 HTTPS

```bash
# 测试本地 HTTPS
curl -I https://kefu.xiaozhusho.top
```

预期返回 `HTTP/2 200`，SSL 证书有效。

---

## 十、进程守护与开机自启

### 10.1 创建 systemd 服务

创建 `/etc/systemd/system/kefu-webman.service`：

```ini
[Unit]
Description=kefu Webman Service
After=network.target mysql.service
Requires=mysql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/html/kefu/server
ExecStart=/usr/bin/php start.php start
ExecStop=/usr/bin/php start.php stop
ExecReload=/usr/bin/php start.php reload
Restart=always
RestartSec=5
StandardOutput=append:/var/log/kefu-webman.out
StandardError=append:/var/log/kefu-webman.err
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
```

### 10.2 启用服务

```bash
sudo systemctl daemon-reload
sudo systemctl enable kefu-webman
sudo systemctl start kefu-webman
sudo systemctl status kefu-webman
```

### 10.3 常用命令

```bash
# 查看状态
sudo systemctl status kefu-webman

# 重启
sudo systemctl restart kefu-webman

# 平滑重启（不中断连接）
sudo systemctl reload kefu-webman

# 停止
sudo systemctl stop kefu-webman

# 查看日志
sudo journalctl -u kefu-webman -f
```

---

## 十一、DNS 域名解析

### 11.1 在域名服务商配置

| 主机记录 | 记录类型 | 记录值 |
| --- | --- | --- |
| @ | A | your-server-ip |
| www | A | your-server-ip |

### 11.2 验证 DNS 解析

```bash
# Linux / Windows
nslookup kefu.xiaozhusho.top
ping kefu.xiaozhusho.top
```

预期返回服务器 IP。

### 11.3 DNS 传播时间

DNS 修改通常需要 5-30 分钟全球生效，最长 48 小时。

---

## 十二、Docker 一键部署

### 12.1 项目支持说明

✅ **系统已完整支持 Docker 部署**：
- `server/Dockerfile` - PHP 8.1-cli-alpine 镜像
- `server/deploy/docker-compose.yml` - 4 服务编排（webman + mysql + redis + nginx）
- `server/deploy/nginx.conf` - Nginx 反向代理配置
- `server/deploy/prometheus.yml` - Prometheus 监控配置
- `server/.dockerignore` - 排除不需要打入镜像的文件

### 12.2 Docker 部署架构

```
┌─────────────────────────────────────────────────────┐
│                   Docker Host                       │
│   ┌────────────────────────────────────────────┐    │
│   │     kefu-nginx (port 80/443)               │    │
│   │     ┌────────────────────────────────┐    │    │
│   │     │  kefu-webman (PHP 8.1 + Webman)│    │    │
│   │     │  port 8787                      │    │    │
│   │     └──────────────┬─────────────────┘    │    │
│   └────────────────────┼──────────────────────┘    │
│                        │                             │
│        ┌───────────────┴───────────────┐             │
│        ▼                               ▼             │
│  ┌──────────────┐              ┌──────────────┐      │
│  │  kefu-mysql  │              │  kefu-redis  │      │
│  │   MySQL 8.0  │              │  Redis 7     │      │
│  │   port 3306  │              │  port 6379   │      │
│  └──────────────┘              └──────────────┘      │
└─────────────────────────────────────────────────────┘
```

### 12.3 一键启动（推荐）

```bash
cd /var/www/html/kefu/server

# 启动所有服务（首次会构建镜像）
docker-compose -f deploy/docker-compose.yml up -d

# 查看服务状态
docker-compose -f deploy/docker-compose.yml ps

# 查看日志
docker-compose -f deploy/docker-compose.yml logs -f webman
```

### 12.4 初始化数据库

首次启动时，MySQL 容器会自动执行 `init.sql` 初始化 47 张表。

如需手动重新初始化：
```bash
# 进入 mysql 容器
docker-compose -f deploy/docker-compose.yml exec mysql bash

# 导入数据
mysql -u kefu -padminkefu kefu < /docker-entrypoint-initdb.d/init.sql
```

### 12.5 升级部署

```bash
# 1. 拉取最新代码
cd /var/www/html/kefu
git pull origin main

# 2. 重新构建并启动
cd server
docker-compose -f deploy/docker-compose.yml up -d --build

# 3. 执行增量迁移（按版本号顺序）
docker-compose -f deploy/docker-compose.yml exec -T mysql mysql -ukefu -padminkefu kefu < sql/migration_xxx.sql

# 4. 重启 webman
docker-compose -f deploy/docker/docker-compose.yml restart webman
```

### 12.6 数据持久化

数据存储在 Docker volumes：
- `kefu_mysql-data` - MySQL 数据
- `kefu_redis-data` - Redis 数据

查看：
```bash
docker volume ls
```

备份：
```bash
docker run --rm -v kefu_mysql-data:/data -v $(pwd)/backup:/backup alpine tar czf /backup/mysql_$(date +%Y%m%d).tar.gz /data
```

### 12.7 常用命令

```bash
# 查看服务状态
docker-compose -f deploy/docker-compose.yml ps

# 重启指定服务
docker-compose -f deploy/docker-compose.yml restart webman

# 进入容器
docker-compose -f deploy/docker-compose.yml exec webman sh

# 实时日志
docker-compose -f deploy/docker-compose.yml logs -f --tail=100 webman

# 停止所有服务
docker-compose -f deploy/docker-compose.yml stop

# 完全清理（包括数据卷）
docker-compose -f deploy/docker-compose.yml down -v
```

### 12.8 Docker 与传统部署对比

| 维度 | Docker 部署 | 传统部署 |
| --- | --- | --- |
| **启动速度** | 5-10 分钟（含构建） | 10-20 分钟 |
| **环境一致性** | 100%（镜像固化） | 依赖服务器环境 |
| **回滚速度** | 秒级（镜像版本切换） | 分钟级（重新部署） |
| **资源占用** | 多 200-500MB（容器开销） | 更轻量 |
| **调试难度** | 需要 docker exec

### 12.1 安全检查

- [ ] 修改所有默认密码（admin/agent01/agent02）
- [ ] 数据库密码使用强密码（≥ 16 位）
- [ ] 防火墙仅开放 22/80/443 端口
- [ ] 数据库仅监听 127.0.0.1
- [ ] HTTPS 证书有效且未过期
- [ ] HTTP 已重定向到 HTTPS

### 12.2 功能检查

- [ ] 数据库迁移全部完成
- [ ] 默认数据已初始化（admin/agent01/agent02）
- [ ] AI 智能体配置（千帆 API Key + App ID）已填入管理后台
- [ ] AI「测试」按钮可成功调用并返回 answer

### 12.3 性能检查

- [ ] PHP OPcache 已启用
- [ ] Nginx gzip 已启用

### 12.4 监控检查

- [ ] systemd 服务开机自启
- [ ] 日志切割已配置（logrotate）
- [ ] 数据库每日自动备份

---

## 十三、上线后验证

### 13.1 健康检查

```bash
# API 健康检查
curl -i https://kefu.xiaozhusho.top/api/health

# 首页可访问
curl -I https://kefu.xiaozhusho.top

# 管理后台可访问
curl -I https://kefu.xiaozhusho.top/admin/login.html

# 客服工作台可访问
curl -I https://kefu.xiaozhusho.top/agent/login.html
```

### 13.2 功能验证

1. **登录管理后台**
   - 访问 https://kefu.xiaozhusho.top/admin/login.html
   - 登录：`admin / admin123`
   - 进入实时看板，看指标是否正常

2. **AI 智能体测试**
   - 进入「AI 智能体」
   - 点击「测试」按钮
   - 应看到 AI 返回真实回复（不再是 conversation_id）

3. **客服工作台**
   - 访问 https://kefu.xiaozhusho.top/agent/login.html
   - 登录：`agent01 / admin123`
   - 进入工作台

4. **访客端 Demo**
   - 访问 https://kefu.xiaozhusho.top/visitor-demo.html
   - 发送消息，应触发 AI 接待

---

## 十五、回滚方案

### 15.1 数据库回滚

```bash
# 1. 停止服务
sudo systemctl stop kefu-webman

# 2. 恢复数据库（需要预先有 dump）
mysql -u kefu -p kefu < /backup/kefu_20260810_pre_upgrade.sql

# 3. 回退代码
cd /var/www/html/kefu
git checkout v1.2.0   # 切回上一个稳定版本

# 4. 重启服务
sudo systemctl start kefu-webman
```

### 14.2 仅代码回滚（数据库兼容）

```bash
cd /var/www/html/kefu
git pull origin main            # 拉取回滚 commit
cd server
composer install --no-dev      # 重装依赖
sudo systemctl reload kefu-webman
```

---

## 十五、运维与监控

### 15.1 日志切割（logrotate）

创建 `/etc/logrotate.d/kefu`：

```
/var/www/html/kefu/server/runtime/logs/*.log {
    daily
    rotate 14
    missingok
    notifempty
    compress
    delaycompress
    create 0640 www-data www-data
    sharedscripts
    postrotate
        sudo systemctl reload kefu-webman > /dev/null 2>/dev/null || true
    endscript
}
```

### 16.2 数据库每日备份

创建 `/usr/local/bin/kefu-backup.sh`：

```bash
#!/bin/bash
BACKUP_DIR=/backup/kefu
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
mysqldump -u kefu -p'your_password' kefu | gzip > $BACKUP_DIR/kefu_$DATE.sql.gz

# 保留最近 30 天
find $BACKUP_DIR -name "kefu_*.sql.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR/kefu_$DATE.sql.gz"
```

```bash
chmod +x /usr/local/bin/kefu-backup.sh

# 添加 cron（每日凌晨 3 点）
sudo crontab -e
# 添加：
0 3 * * * /usr/local/bin/kefu-backup.sh >> /var/log/kefu-backup.log 2>&1
```

### 15.3 监控告警（可选方案）

**A. UptimeRobot**（免费外部监控）
- 注册 https://uptimerobot.com
- 添加监控：`https://kefu.xiaozhusho.top/api/health`
- 告警方式：邮件 / 短信

**B. Prometheus + Grafana**（自建监控）
- 部署 node-exporter 采集服务器指标
- 部署 mysql-exporter 采集数据库指标
- 配置 Grafana Dashboard

---

## 十七、常见问题 FAQ

### Q1：访问首页返回 502 Bad Gateway？
**A**：
- 检查 webman 是否启动：`systemctl status kefu-webman`
- 检查端口 8787 是否监听：`ss -tlnp | grep 8787`
- 查看错误日志：`journalctl -u kefu-webman -n 50`

### Q2：数据库连接失败？
**A**：
- 检查 MySQL 服务状态：`systemctl status mysql`
- 验证数据库账号：`mysql -u kefu -p kefu -e "SELECT 1"`
- 检查 `.env` 中 DB_PASSWORD 是否正确

### Q3：AI 调用返回 "缺少 answer 字段"？
**A**：
- 进入管理后台 → AI 智能体 → 检查 endpoint 是否为 `https://qianfan.baidubce.com/v2/app/conversation/runs`
- 确认千帆智能体已发布且 API Key 有权限

### Q4：HTTPS 证书过期？
**A**：
- Let's Encrypt 证书 90 天过期
- certbot 已自动配置续期任务（每日运行）
- 手动续期：`certbot renew`

### Q5：如何修改默认密码？
**A**：
- 登录管理后台 → 员工列表 → 选中员工 → 重置密码
- 或直接在数据库修改（bcrypt 加密）

### Q6：如何查看实时日志？
**A**：
```bash
# webman 主日志
tail -f /var/www/html/kefu/server/runtime/logs/webman.log

# systemd 日志
journalctl -u kefu-webman -f

# Nginx 访问日志
tail -f /var/log/nginx/kefu.access.log
```

### Q7：如何升级到新版本？
**A**：
1. 备份数据库（`/usr/local/bin/kefu-backup.sh`）
2. 拉取新代码：`git pull origin main`
3. 执行新增的 SQL 迁移文件
4. 重启服务：`sudo systemctl restart kefu-webman`
5. 验证功能

### Q8：磁盘空间不足？
**A**：
```bash
# 查看日志大小
du -sh /var/www/html/kefu/server/runtime/logs/*

# 清理旧日志（保留最近 14 天）
find /var/www/html/kefu/server/runtime/logs/ -name "*.log" -mtime +14 -delete
```

### Q9：CPU / 内存占用高？
**A**：
```bash
# 查看进程
ps aux --sort=-%cpu | head -10
ps aux --sort=-%rss | head -10

# 调整 webman 进程数（编辑 server/config/server.php 中的 worker_num）
```

### Q10：如何迁移到新服务器？
**A**：
1. 在旧服务器备份数据库：`mysqldump ... > backup.sql`
2. 在新服务器上重复本文档的第 7-9 步
3. 在新服务器导入数据库：`mysql ... < backup.sql`
5. 修改域名 DNS 解析到新服务器 IP
6. 等待 DNS 传播（5-30 分钟）
7. 旧服务器服务下线

---

## 附录 A：完整部署检查表

```
[ ] 1.  服务器：Ubuntu 22.04 / CentOS 8+
[ ] 2.  安装：PHP 8.1 + MySQL 8.0 + Nginx + Composer
[ ] 3.  创建数据库 kefu + 用户 kefu + 密码
[ ] 4.  上传代码到 /var/www/html/kefu
[ ] 5.  composer install --no-dev --optimize-autoloader
[ ] 6.  配置 .env（DB_*, WS_*）
[ ] 7.  设置目录权限（runtime 775）
[ ] 8.  执行 init.sql 初始化数据库
[ ] 9.  执行所有 migration_*.sql 增量迁移
[ ] 10. 测试：php start.php start（前台启动观察无报错）
[ ] 11. 停止前台：Ctrl+C，改用 systemd 守护
[ ] 12. 配置 /etc/systemd/system/kefu-webman.service
[ ] 13. systemctl enable kefu-webman
[ ] 14. 配置 /etc/nginx/sites-available/kefu
[ ] 15. 申请 SSL 证书：certbot --nginx -d kefu.xiaozhusho.top
[ ] 16. nginx -t && systemctl reload nginx
[ ] 17. DNS 解析 A 记录 → 服务器 IP
[ ] 18. 验证 HTTPS 访问 https://kefu.xiaozhusho.top
[ ] 19. 修改默认密码 admin/agent01/agent02
[ ] 20. 配置千帆 API Key + App ID（管理后台）
[ ] 21. 配置数据库自动备份（cron）
[ ] 22. 配置日志切割（logrotate）
[ ] 23. 配置监控告警（UptimeRobot 或自建）
```

---

## 附录 B：常用命令速查

```bash
# 服务管理
sudo systemctl status kefu-webman
sudo systemctl restart kefu-webman
sudo systemctl reload kefu-webman
sudo systemctl stop kefu-webman
sudo systemctl start kefu-webman

# 日志查看
tail -f /var/www/html/kefu/server/runtime/logs/webman.log
journalctl -u kefu-webman -f

# 数据库
mysql -u kefu -p kefu
mysqldump -u kefu -p kefu > backup.sql
mysql -u kefu -p kefu < backup.sql

# Nginx
sudo nginx -t
sudo systemctl reload nginx
sudo tail -f /var/log/nginx/kefu.error.log

# 代码更新
cd /var/www/html/kefu
git pull origin main
cd server
composer install --no-dev
sudo systemctl reload kefu-webman
```

---

## 附录 C：联系方式

| 项目 | 信息 |
| --- | --- |
| 项目名 | kefu · 企业级 AI 智能客服平台 |
| 在线域名 | https://kefu.xiaozhusho.top |
| 开发团队 | kefu 开发团队 zero |
| 邮箱 | 619864585@qq.com |
| 技术栈 | PHP 8 + Webman + MySQL 8 + 百度千帆 App |

---

**文档维护**：kefu 开发团队 zero
**最后更新**：2026-08-10
**邮箱**：619864585@qq.com