安装指南

本文档将指导您完成 CarefreeCMS 的安装和配置。

环境准备

系统要求

推荐配置

PHP 8.2+
MySQL 8.0+
Node.js 18+
2GB+ 内存
SSD 硬盘

检查 PHP 版本和扩展

# 检查 PHP 版本
php -v

# 检查已安装的扩展
php -m

确保以下扩展已启用：

PDO
pdo_mysql
mbstring
openssl
json
fileinfo
gd (或 imagick)
zip

安装步骤

1. 获取源代码

方式一：Git 克隆（推荐）

git clone https://github.com/carefree-code/CarefreeCMS.git
cd carefreecms

方式二：下载压缩包 从 GitHub Releases 下载最新版本并解压。

2. 安装后端

2.1 安装 Composer 依赖

cd backend
composer install

提示

如果 Composer 下载速度慢，可以使用国内镜像：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

2.2 配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，配置数据库连接：

[DATABASE]
DB_HOST = 127.0.0.1
DB_NAME = cms_database
DB_USER = root
DB_PASS = your_password
DB_PORT = 3306
DB_CHARSET = utf8mb4

[JWT]
# 生成强随机密钥（必需！）
# 使用命令：php -r "echo base64_encode(random_bytes(32));"
JWT_SECRET = your_strong_random_secret_key_here
JWT_EXPIRE = 7200

[CORS]
# 开发环境允许的前端地址
CORS_ALLOWED_ORIGINS = http://localhost:5173,http://localhost:3000

安全警告

必须设置强随机 JWT_SECRET，不能使用默认值
生产环境请使用复杂的数据库密码

2.3 创建数据库

mysql -u root -p -e "CREATE DATABASE cms_database DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

2.4 导入数据库

按以下顺序导入 SQL 文件（从项目 docs/ 目录）：

# 1. 导入基础设计（必需）
mysql -u root -p cms_database < docs/database_design.sql

# 2. 导入系统管理表（必需）
mysql -u root -p cms_database < docs/database_system.sql

# 3. 导入其他功能模块（可选）
mysql -u root -p cms_database < docs/database_template_theme.sql    # 模板主题
mysql -u root -p cms_database < docs/database_article_versions.sql  # 文章版本
mysql -u root -p cms_database < docs/database_topics.sql            # 专题管理
mysql -u root -p cms_database < docs/database_custom_fields_and_models.sql  # 自定义字段
mysql -u root -p cms_database < docs/database_links_and_ads.sql     # 友链和广告
mysql -u root -p cms_database < docs/database_sliders.sql           # 幻灯片
mysql -u root -p cms_database < docs/database_seo.sql               # SEO功能

提示

如需完整功能，建议导入所有 SQL 文件。

2.5 配置目录权限

# 确保以下目录可写
chmod -R 755 backend/runtime
chmod -R 755 backend/public/uploads
chmod -R 755 backend/html

创建静态文件目录：

cd backend
mkdir -p html/assets/images/placeholder

2.6 启动后端服务

# 在 backend 目录下
php think run

服务将运行在 http://localhost:8000

3. 安装前端

3.1 安装 Node.js 依赖

cd frontend
npm install

提示

如果 npm 安装速度慢，可以使用 cnpm 或配置国内镜像：

npm config set registry https://registry.npmmirror.com

3.2 配置 API 地址

编辑 frontend/.env.development 文件：

VITE_API_BASE_URL=http://localhost:8000

3.3 启动前端服务

npm run dev

前端将运行在 http://localhost:5173

验证安装

1. 访问管理后台

打开浏览器访问：http://localhost:5173

2. 登录系统

使用默认账号登录：

用户名：admin
密码：admin123

安全提示

首次登录后请立即修改密码！

3. 检查功能

登录后检查：

[ ] 仪表板数据是否正常显示
[ ] 文章列表是否可以访问
[ ] 上传文件功能是否正常
[ ] 设置页面是否可以保存

生产环境部署

宝塔面板部署

宝塔面板是一款简单好用的 Linux/Windows 服务器运维管理面板，适合快速部署 CarefreeCMS。

前置要求

已安装宝塔面板（安装教程）
服务器配置：2核4G内存以上

1. 安装运行环境

在宝塔面板中安装以下软件：

Nginx 1.20+ 或 Apache 2.4+
PHP 8.2（编译安装，选择以下扩展）：
- opcache
- redis
- memcached
- imagemagick
- fileinfo
- pdo_mysql
- mbstring
- openssl
- zip
MySQL 8.0+
Redis 7.0+（可选，推荐用于缓存）

2. 创建网站

点击【网站】→【添加站点】
域名填写：www.example.com（你的域名）
根目录：/www/wwwroot/carefreecms
PHP 版本：选择 8.2
数据库：选择 MySQL，输入数据库名 cms_database

3. 上传代码

方式一：通过 Git（推荐）

在宝塔终端或 SSH 连接服务器：

cd /www/wwwroot
git clone https://github.com/carefree-code/CarefreeCMS.git carefreecms
cd carefreecms

方式二：手动上传

使用宝塔【文件】功能上传压缩包
解压到 /www/wwwroot/carefreecms

4. 配置后端

cd /www/wwwroot/carefreecms/backend

# 安装 Composer 依赖
composer install --optimize-autoloader --no-dev

# 配置环境变量
cp .env.example .env

编辑 .env 文件：

[DATABASE]
DB_HOST = 127.0.0.1
DB_NAME = cms_database
DB_USER = cms_user
DB_PASS = your_secure_password
DB_PORT = 3306

[JWT]
JWT_SECRET = your_production_jwt_secret_here
JWT_EXPIRE = 7200

[APP]
APP_DEBUG = false  # 生产环境关闭调试

5. 导入数据库

在宝塔【数据库】面板：

找到 cms_database 数据库
点击【导入】
按顺序导入以下 SQL 文件：
- docs/database_design.sql
- docs/database_system.sql
- 其他功能模块 SQL 文件

或使用命令行：

cd /www/wwwroot/carefreecms
mysql -u cms_user -p cms_database < docs/database_design.sql
mysql -u cms_user -p cms_database < docs/database_system.sql

6. 设置目录权限

在宝塔【文件】中设置权限：

backend/runtime → 755
backend/public/uploads → 755
backend/html → 755

或使用命令：

chmod -R 755 /www/wwwroot/carefreecms/backend/runtime
chmod -R 755 /www/wwwroot/carefreecms/backend/public/uploads
chmod -R 755 /www/wwwroot/carefreecms/backend/html
chown -R www:www /www/wwwroot/carefreecms

7. 配置 Nginx

在宝塔【网站】→【设置】→【配置文件】中修改：

server {
    listen 80;
    server_name www.example.com;
    root /www/wwwroot/carefreecms/backend/public;
    index index.php index.html;

    # API 路由
    location /api {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php?s=$1 last;
            break;
        }
    }

    # PHP 处理
    location ~ \.php$ {
        fastcgi_pass unix:/tmp/php-cgi-82.sock;  # 根据实际 PHP 版本调整
        fastcgi_index index.php;
        include fastcgi.conf;
    }

    # 静态文件缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf)$ {
        expires 30d;
        access_log off;
    }

    # 前端路由（如果前后端分离）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
}

8. 配置 SSL（推荐）

在宝塔【网站】→【设置】→【SSL】
选择【Let's Encrypt】免费证书
输入域名并申请
开启【强制 HTTPS】

9. 构建前端

cd /www/wwwroot/carefreecms/frontend

# 安装依赖
npm install

# 配置生产环境 API 地址
cat > .env.production << EOF
VITE_API_BASE_URL=https://www.example.com
EOF

# 构建生产版本
npm run build

构建完成后，将 dist 目录内容复制到网站根目录或配置为独立前端站点。

10. 配置守护进程（可选）

为了保持 PHP 服务常驻，可使用宝塔的【Supervisor】管理器：

安装 Supervisor 管理器
添加守护进程：
- 名称：carefreecms
- 运行目录：/www/wwwroot/carefreecms/backend
- 启动命令：/www/server/php/82/bin/php think queue:listen

11. 设置计划任务

在宝塔【计划任务】中添加：

# 每分钟执行一次（用于定时任务）
* * * * * cd /www/wwwroot/carefreecms/backend && php think

Docker 部署

使用 Docker 可以快速部署 CarefreeCMS，并确保环境一致性。

前置要求

Docker 20.10+
Docker Compose 2.0+

1. 创建 Dockerfile

在项目根目录创建 Dockerfile：

# Backend Dockerfile
FROM php:8.2-fpm-alpine

# 安装系统依赖
RUN apk add --no-cache \
    nginx \
    mysql-client \
    freetype-dev \
    libjpeg-turbo-dev \
    libpng-dev \
    libzip-dev \
    zip \
    unzip \
    git \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
        pdo_mysql \
        mysqli \
        gd \
        zip \
        opcache \
        pcntl \
        bcmath

# 安装 Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# 设置工作目录
WORKDIR /var/www/html

# 复制后端代码
COPY backend/ .

# 安装 PHP 依赖
RUN composer install --no-dev --optimize-autoloader

# 设置权限
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 runtime public/uploads html

# 暴露端口
EXPOSE 9000

CMD ["php-fpm"]

2. 创建 docker-compose.yml

在项目根目录创建：

version: '3.8'

services:
  # MySQL 数据库
  mysql:
    image: mysql:8.0
    container_name: carefreecms_mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: cms_database
      MYSQL_USER: cms_user
      MYSQL_PASSWORD: cms_password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./docs:/docker-entrypoint-initdb.d:ro  # 自动导入 SQL
    ports:
      - "3306:3306"
    networks:
      - carefreecms_network

  # Redis 缓存
  redis:
    image: redis:7-alpine
    container_name: carefreecms_redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    networks:
      - carefreecms_network

  # PHP 后端
  backend:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: carefreecms_backend
    restart: unless-stopped
    working_dir: /var/www/html
    volumes:
      - ./backend:/var/www/html
      - ./backend/public/uploads:/var/www/html/public/uploads
    environment:
      DB_HOST: mysql
      DB_NAME: cms_database
      DB_USER: cms_user
      DB_PASS: cms_password
      REDIS_HOST: redis
    depends_on:
      - mysql
      - redis
    networks:
      - carefreecms_network

  # Nginx 服务器
  nginx:
    image: nginx:alpine
    container_name: carefreecms_nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./backend/public:/var/www/html/public:ro
      - ./frontend/dist:/var/www/html/frontend:ro
      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./docker/nginx/conf.d:/etc/nginx/conf.d:ro
    depends_on:
      - backend
    networks:
      - carefreecms_network

  # 前端（可选，用于开发）
  frontend:
    image: node:18-alpine
    container_name: carefreecms_frontend
    working_dir: /app
    volumes:
      - ./frontend:/app
    command: sh -c "npm install && npm run dev"
    ports:
      - "5173:5173"
    environment:
      VITE_API_BASE_URL: http://localhost:80
    networks:
      - carefreecms_network

volumes:
  mysql_data:
    driver: local
  redis_data:
    driver: local

networks:
  carefreecms_network:
    driver: bridge

3. 创建 Nginx 配置

创建 docker/nginx/conf.d/default.conf：

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;
    index index.php index.html;

    # API 路由
    location /api {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP 处理
    location ~ \.php$ {
        fastcgi_pass backend:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # 前端
    location / {
        root /var/www/html/frontend;
        try_files $uri $uri/ /index.html;
    }

    # 静态文件
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 30d;
        access_log off;
    }
}

4. 启动服务

# 启动所有服务
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 停止并删除数据
docker-compose down -v

5. 初始化数据库

# 进入 MySQL 容器
docker-compose exec mysql bash

# 导入数据库
mysql -u cms_user -p cms_database < /docker-entrypoint-initdb.d/database_design.sql

6. 访问系统

前端：http://localhost
后端 API：http://localhost/api
开发模式前端：http://localhost:5173

云服务器部署

阿里云/腾讯云 ECS 部署

1. 购买服务器

推荐配置：

CPU：2核+
内存：4GB+
磁盘：40GB+ SSD
带宽：3Mbps+
系统：Ubuntu 22.04 LTS / CentOS 7+

2. 安装 LNMP 环境

Ubuntu/Debian 系统：

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

# 安装 Nginx
sudo apt install nginx -y

# 安装 PHP 8.2
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install php8.2-fpm php8.2-mysql php8.2-mbstring php8.2-xml \
    php8.2-curl php8.2-zip php8.2-gd php8.2-redis -y

# 安装 MySQL
sudo apt install mysql-server -y

# 安装 Redis
sudo apt install redis-server -y

# 安装 Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

CentOS/RHEL 系统：

# 安装 EPEL 仓库
sudo yum install epel-release -y

# 安装 Nginx
sudo yum install nginx -y

# 安装 PHP 8.2
sudo yum install http://rpms.remirepo.net/enterprise/remi-release-7.rpm -y
sudo yum install yum-utils -y
sudo yum-config-manager --enable remi-php82
sudo yum install php php-fpm php-mysql php-mbstring php-xml \
    php-curl php-zip php-gd php-redis -y

# 安装 MySQL
sudo yum install mysql-server -y

# 安装 Redis
sudo yum install redis -y

3. 配置防火墙

# Ubuntu (UFW)
sudo ufw allow 22    # SSH
sudo ufw allow 80    # HTTP
sudo ufw allow 443   # HTTPS
sudo ufw enable

# CentOS (firewalld)
sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

4. 配置安全组

在云服务器控制台添加安全组规则：

入站：22 (SSH), 80 (HTTP), 443 (HTTPS)
出站：全部允许

5. 部署代码

参照宝塔面板部署步骤的 3-9 步。

6. 配置自动备份

创建备份脚本 /root/backup_cms.sh：

#!/bin/bash

# 配置
BACKUP_DIR="/root/backups"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="cms_database"
DB_USER="cms_user"
DB_PASS="your_password"

# 创建备份目录
mkdir -p $BACKUP_DIR

# 备份数据库
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# 备份上传文件
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /www/wwwroot/carefreecms/backend/public/uploads

# 删除 7 天前的备份
find $BACKUP_DIR -type f -mtime +7 -delete

echo "Backup completed: $DATE"

设置定时任务：

chmod +x /root/backup_cms.sh
crontab -e

# 添加：每天凌晨 2 点备份
0 2 * * * /root/backup_cms.sh >> /var/log/cms_backup.log 2>&1

Vercel/Netlify 前端部署

如果采用前后端分离架构，可将前端部署到 CDN 平台。

Vercel 部署

安装 Vercel CLI：

npm install -g vercel

在 frontend 目录创建 vercel.json：

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

部署：

cd frontend
vercel --prod

Netlify 部署

在 frontend 目录创建 netlify.toml：

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

部署：

# 安装 Netlify CLI
npm install -g netlify-cli

# 部署
cd frontend
netlify deploy --prod

常见问题

Composer 安装失败

问题：composer install 超时或失败

解决：

# 使用中国镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 增加超时时间
composer install --timeout=3000

数据库连接失败

问题：SQLSTATE[HY000] [2002] Connection refused

解决：

检查 MySQL 服务是否启动
验证 .env 中的数据库配置
确认数据库用户权限

CORS 跨域错误

问题：前端请求后端 API 出现 CORS 错误

解决：确保 .env 文件中配置了正确的 CORS_ALLOWED_ORIGINS：

CORS_ALLOWED_ORIGINS = http://localhost:5173,http://localhost:3000

前端白屏或 404

问题：访问前端页面白屏或显示 404

解决：

检查 npm run dev 是否正常启动
查看浏览器控制台是否有错误
确认 API 地址配置是否正确

文件上传失败

问题：上传文件时提示权限错误

解决：

# 设置上传目录权限
chmod -R 755 backend/public/uploads
chown -R www-data:www-data backend/public/uploads  # Linux

下一步

安装完成后，建议：

📖 阅读快速开始指南
⚙️ 查看配置说明
🎨 了解模板系统
📝 学习文章管理

获取帮助

如果遇到安装问题：

💬 加入 QQ 群：113572201
🐛 提交 Issue：GitHub Issues
📧 邮件支持：support@carefreecms.com