KnowledgeBase/docs/DEPLOYMENT.md

知识库系统部署指南

本文档提供知识库系统的详细部署步骤和配置说明。

目录

1. 服务器要求
2. 安装依赖
3. 项目部署
4. 配置服务
5. 性能优化
6. 监控和维护
7. 故障排除

服务器要求

最低配置

• CPU: 2 核心
• 内存: 4GB RAM
• 存储: 50GB SSD
• 操作系统: Ubuntu 20.04+ / CentOS 8+ / Debian 11+

推荐配置

• CPU: 4 核心
• 内存: 8GB RAM
• 存储: 100GB SSD
• 操作系统: Ubuntu 22.04 LTS

软件要求

• PHP 8.1 或更高版本
• MySQL 8.0+ 或 PostgreSQL 13+
• Redis 6.0+
• Nginx 1.18+ 或 Apache 2.4+
• Composer 2.x
• Node.js 18+ 和 npm
• Meilisearch 1.5+
• Pandoc 2.x+（用于文档转换）
• Supervisor（用于管理队列进程）

安装依赖

1. 安装 PHP 和扩展

Ubuntu/Debian

sudo apt update
sudo apt install -y php8.1 php8.1-fpm php8.1-cli php8.1-common \
    php8.1-mysql php8.1-pgsql php8.1-redis php8.1-xml php8.1-mbstring \
    php8.1-curl php8.1-zip php8.1-gd php8.1-intl php8.1-bcmath

CentOS/RHEL

sudo dnf install -y php php-fpm php-cli php-common php-mysqlnd \
    php-pgsql php-redis php-xml php-mbstring php-curl php-zip \
    php-gd php-intl php-bcmath

2. 安装 Composer

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

3. 安装 Node.js 和 npm

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

4. 安装 MySQL

sudo apt install -y mysql-server
sudo mysql_secure_installation

创建数据库和用户：

CREATE DATABASE knowledge_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kb_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON knowledge_base.* TO 'kb_user'@'localhost';
FLUSH PRIVILEGES;

5. 安装 Redis

sudo apt install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

6. 安装 Meilisearch

使用 Docker（推荐）

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -v $(pwd)/storage/meilisearch:/meili_data \
  -e MEILI_MASTER_KEY='your_master_key_here' \
  getmeili/meilisearch:v1.5

直接安装

curl -L https://install.meilisearch.com | sh
sudo mv ./meilisearch /usr/local/bin/

创建 systemd 服务：

sudo nano /etc/systemd/system/meilisearch.service

内容：

[Unit]
Description=Meilisearch
After=network.target

[Service]
Type=simple
User=www-data
ExecStart=/usr/local/bin/meilisearch --master-key="your_master_key_here" --db-path=/var/lib/meilisearch/data
Restart=on-failure

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable meilisearch
sudo systemctl start meilisearch

7. 安装 Pandoc

sudo apt install -y pandoc

或下载最新版本：

wget https://github.com/jgm/pandoc/releases/download/3.1.11/pandoc-3.1.11-1-amd64.deb
sudo dpkg -i pandoc-3.1.11-1-amd64.deb

8. 安装 Supervisor

sudo apt install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

项目部署

1. 克隆项目

cd /var/www
sudo git clone <repository-url> knowledge-base
cd knowledge-base

2. 设置权限

sudo chown -R www-data:www-data /var/www/knowledge-base
sudo chmod -R 755 /var/www/knowledge-base
sudo chmod -R 775 /var/www/knowledge-base/storage
sudo chmod -R 775 /var/www/knowledge-base/bootstrap/cache

3. 安装依赖

# PHP 依赖
composer install --no-dev --optimize-autoloader

# 前端依赖
npm install
npm run build

4. 配置环境变量

cp .env.example .env
nano .env

配置以下关键参数：

APP_NAME="知识库系统"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=knowledge_base
DB_USERNAME=kb_user
DB_PASSWORD=your_secure_password

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=your_master_key_here
SCOUT_DRIVER=meilisearch

DOCUMENT_CONVERSION_DRIVER=pandoc
PANDOC_PATH=/usr/bin/pandoc
CONVERSION_TIMEOUT=300

FILESYSTEM_DISK=local

5. 生成应用密钥

php artisan key:generate

6. 运行数据库迁移

php artisan migrate --force

7. 创建存储目录

mkdir -p storage/app/private/documents
mkdir -p storage/app/private/markdown
sudo chown -R www-data:www-data storage/app/private
sudo chmod -R 775 storage/app/private

8. 优化应用

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan filament:optimize

9. 创建管理员用户

php artisan make:filament-user

配置服务

1. 配置 Nginx

创建站点配置：

sudo nano /etc/nginx/sites-available/knowledge-base

内容：

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;
    root /var/www/knowledge-base/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    # 文件上传大小限制
    client_max_body_size 50M;
}

启用站点：

sudo ln -s /etc/nginx/sites-available/knowledge-base /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

2. 配置 SSL（使用 Let's Encrypt）

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

3. 配置队列工作进程

创建 Supervisor 配置：

sudo nano /etc/supervisor/conf.d/knowledge-base-worker.conf

内容：

[program:knowledge-base-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/knowledge-base/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/knowledge-base/storage/logs/worker.log
stopwaitsecs=3600

重新加载 Supervisor：

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start knowledge-base-worker:*

4. 配置定时任务

编辑 crontab：

sudo crontab -e -u www-data

添加：

* * * * * cd /var/www/knowledge-base && php artisan schedule:run >> /dev/null 2>&1

性能优化

1. PHP-FPM 优化

编辑 PHP-FPM 配置：

sudo nano /etc/php/8.1/fpm/pool.d/www.conf

调整参数：

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500

重启 PHP-FPM：

sudo systemctl restart php8.1-fpm

2. Redis 优化

编辑 Redis 配置：

sudo nano /etc/redis/redis.conf

调整参数：

maxmemory 2gb
maxmemory-policy allkeys-lru

重启 Redis：

sudo systemctl restart redis-server

3. MySQL 优化

编辑 MySQL 配置：

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

添加优化参数：

[mysqld]
innodb_buffer_pool_size = 2G
innodb_log_file_size = 256M
innodb_flush_log_at_trx_commit = 2
innodb_flush_method = O_DIRECT
query_cache_size = 0
query_cache_type = 0

重启 MySQL：

sudo systemctl restart mysql

4. Opcache 配置

编辑 PHP 配置：

sudo nano /etc/php/8.1/fpm/conf.d/10-opcache.ini

内容：

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=60
opcache.fast_shutdown=1

监控和维护

1. 日志监控

查看应用日志：

tail -f /var/www/knowledge-base/storage/logs/laravel.log

查看队列工作进程日志：

tail -f /var/www/knowledge-base/storage/logs/worker.log

查看 Nginx 日志：

tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

2. 定期备份

数据库备份

创建备份脚本：

sudo nano /usr/local/bin/backup-kb-db.sh

内容：

#!/bin/bash
BACKUP_DIR="/var/backups/knowledge-base"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

mysqldump -u kb_user -p'your_secure_password' knowledge_base | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# 保留最近 7 天的备份
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +7 -delete

设置权限并添加到 crontab：

sudo chmod +x /usr/local/bin/backup-kb-db.sh
sudo crontab -e

添加每日备份任务：

0 2 * * * /usr/local/bin/backup-kb-db.sh

文件备份

sudo nano /usr/local/bin/backup-kb-files.sh

内容：

#!/bin/bash
BACKUP_DIR="/var/backups/knowledge-base"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

tar -czf $BACKUP_DIR/files_$DATE.tar.gz \
    /var/www/knowledge-base/storage/app/private/documents \
    /var/www/knowledge-base/storage/app/private/markdown

# 保留最近 7 天的备份
find $BACKUP_DIR -name "files_*.tar.gz" -mtime +7 -delete

3. 系统监控

安装监控工具：

sudo apt install -y htop iotop nethogs

监控系统资源：

# CPU 和内存
htop

# 磁盘 I/O
iotop

# 网络流量
nethogs

4. 应用健康检查

创建健康检查脚本：

sudo nano /usr/local/bin/check-kb-health.sh

内容：

#!/bin/bash

# 检查 Web 服务
if ! curl -f http://localhost > /dev/null 2>&1; then
    echo "Web service is down!"
    sudo systemctl restart nginx
fi

# 检查队列工作进程
if ! sudo supervisorctl status knowledge-base-worker:* | grep RUNNING > /dev/null; then
    echo "Queue worker is down!"
    sudo supervisorctl restart knowledge-base-worker:*
fi

# 检查 Meilisearch
if ! curl -f http://localhost:7700/health > /dev/null 2>&1; then
    echo "Meilisearch is down!"
    sudo systemctl restart meilisearch
fi

添加到 crontab（每 5 分钟检查一次）：

*/5 * * * * /usr/local/bin/check-kb-health.sh

故障排除

1. 文件上传失败

检查 PHP 配置：

php -i | grep upload_max_filesize
php -i | grep post_max_size

如需调整，编辑 PHP 配置：

sudo nano /etc/php/8.1/fpm/php.ini

修改：

upload_max_filesize = 50M
post_max_size = 50M

重启 PHP-FPM：

sudo systemctl restart php8.1-fpm

2. 队列任务不执行

检查队列工作进程状态：

sudo supervisorctl status knowledge-base-worker:*

重启工作进程：

sudo supervisorctl restart knowledge-base-worker:*

查看队列日志：

tail -f /var/www/knowledge-base/storage/logs/worker.log

3. Meilisearch 连接失败

检查 Meilisearch 状态：

curl http://localhost:7700/health

检查 Meilisearch 日志：

sudo journalctl -u meilisearch -f

重启 Meilisearch：

sudo systemctl restart meilisearch

4. 文档转换失败

检查 Pandoc 是否安装：

which pandoc
pandoc --version

检查转换日志：

grep "conversion" /var/www/knowledge-base/storage/logs/laravel.log

手动测试转换：

pandoc test.docx -o test.md

5. 权限问题

重置存储目录权限：

cd /var/www/knowledge-base
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

6. 缓存问题

清除所有缓存：

cd /var/www/knowledge-base
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

重新生成缓存：

php artisan config:cache
php artisan route:cache
php artisan view:cache

更新部署

1. 拉取最新代码

cd /var/www/knowledge-base
sudo -u www-data git pull origin main

2. 更新依赖

sudo -u www-data composer install --no-dev --optimize-autoloader
sudo -u www-data npm install
sudo -u www-data npm run build

3. 运行迁移

php artisan migrate --force

4. 清除和重建缓存

php artisan cache:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan filament:optimize

5. 重启服务

sudo systemctl reload php8.1-fpm
sudo systemctl reload nginx
sudo supervisorctl restart knowledge-base-worker:*

安全建议

1. 定期更新系统和软件包

sudo apt update && sudo apt upgrade -y

2. 配置防火墙

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

3. 禁用不必要的 PHP 函数 编辑 php.ini，添加：

disable_functions = exec,passthru,shell_exec,system,proc_open,popen

4. 设置强密码策略
5. 定期审查安全日志
6. 启用 HTTPS
7. 限制文件上传类型
8. 定期备份数据

联系支持

如遇到部署问题，请联系技术支持团队。

---

最后更新：2025-12-05