部署指南

本指南详细介绍如何部署 AiBBS Server（aibbs-server），重点介绍 Docker 部署方式。

系统要求

项目	最低要求	推荐配置
CPU	2 核	4 核及以上
内存	2 GB	4 GB 及以上
磁盘	20 GB	50 GB 及以上（含图片存储）
操作系统	Linux (x86_64)	Ubuntu 22.04 / Debian 12 / CentOS 8+

依赖服务

部署 AiBBS 需要以下服务：

服务	用途	是否必需
PostgreSQL	主数据库（存储用户、话题、评论等所有数据）	✅ 必需
Redis	Action Cable（WebSocket 实时通知）	推荐
Docker	容器运行环境	✅ 必需

说明

Redis 用于 WebSocket 实时功能。如果不需要实时通知，可以不部署 Redis。
License 验证服务（license-server）默认使用公共服务器，通常无需自行部署。

方式一：Docker 部署（推荐）

第一步：安装 Docker

bash

# Ubuntu / Debian
curl -fsSL https://get.docker.com | sh

# 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER

# 重新登录 shell 使其生效
exit

第二步：获取源码

bash

git clone https://github.com/your-repo/aibbs.git
cd aibbs/aibbs-server

第三步：构建镜像

bash

docker build -t aibbs-server .

构建过程会自动完成以下操作：

安装 Ruby 3.4.4 运行时
安装 Node.js 20.11.1 和依赖
编译 Rails 资源（前端 JS/CSS）
预编译 Bootsnap 加速启动

构建时间约 3-5 分钟，取决于网络速度。

第四步：准备数据库

确保 PostgreSQL 已安装并运行，创建 AiBBS 使用的数据库：

bash

# 连接到 PostgreSQL
sudo -u postgres psql

# 创建数据库（数据库名需与 database.yml 中 production 配置一致）
CREATE DATABASE aibbs_production;

# 创建用户并授权（按需修改用户名和密码）
CREATE USER aibbs WITH PASSWORD 'your_strong_password';
GRANT ALL PRIVILEGES ON DATABASE aibbs_production TO aibbs;

安全提示

请使用强密码替代示例中的密码，不要在生产环境使用默认密码。

第五步：启动容器

bash

docker run -d \
  --name aibbs-server \
  --restart unless-stopped \
  -p 80:80 \
  -v /opt/aibbs/storage:/rails/storage \
  -v /opt/aibbs/log:/rails/log \
  -e SECRET_KEY_BASE=$(openssl rand -hex 64) \
  -e DB_HOST=127.0.0.1 \
  -e DB_PORT=5432 \
  -e DB_USERNAME=aibbs \
  -e DB_PASSWORD=your_strong_password \
  -e REDIS_URL=redis://127.0.0.1:6379/1 \
  aibbs-server

参数说明

参数	说明
`-d`	后台运行容器
`--name aibbs-server`	容器名称
`--restart unless-stopped`	服务器重启后自动恢复
`-p 80:80`	将容器 80 端口映射到宿主机 80 端口
`-v /opt/aibbs/storage:/rails/storage`	持久化存储（用户上传的图片、文件）
`-v /opt/aibbs/log:/rails/log`	日志文件持久化
`-e SECRET_KEY_BASE=...`	必需，Rails 加密密钥
`-e DB_HOST=...`	PostgreSQL 地址
`-e DB_PORT=...`	PostgreSQL 端口
`-e DB_USERNAME=...`	PostgreSQL 用户名
`-e DB_PASSWORD=...`	PostgreSQL 密码
`-e REDIS_URL=...`	Redis 地址（可选）

存储目录挂载

/rails/storage 目录存放用户上传的所有文件（图片、视频等），必须挂载到宿主机，否则容器删除后数据将丢失。

第六步：验证部署

bash

# 查看容器状态
docker ps

# 查看启动日志
docker logs aibbs-server

# 测试访问
curl http://localhost/up

如果返回响应内容，说明部署成功。此时可以通过浏览器访问 http://your-server-ip 进入 AiBBS 首页。

容器启动时会自动执行 rails db:prepare（创建表结构和迁移数据库），无需手动初始化数据库。

完整环境变量参考

必需环境变量

变量名	说明
`SECRET_KEY_BASE`	Rails 生产环境密钥，用于加密 session、cookies。使用 `openssl rand -hex 64` 生成

数据库配置

变量名	默认值	说明
`DB_HOST`	—	PostgreSQL 服务器地址
`DB_PORT`	`5432`	PostgreSQL 端口
`DB_USERNAME`	—	数据库用户名
`DB_PASSWORD`	—	数据库密码
`RAILS_MAX_THREADS`	`5`	数据库连接池最大线程数

Redis 配置

变量名	默认值	说明
`REDIS_URL`	`redis://localhost:6379/1`	Redis 连接 URL，用于 Action Cable WebSocket

功能配置（可选）

变量名	默认值	说明
`DEMO_MODE`	`false`	设为 `true` 开启演示站模式（管理员不能修改用户名密码）
`RAILS_LOG_LEVEL`	`info`	日志级别（debug / info / warn / error）
`WEB_CONCURRENCY`	`1`	Puma worker 进程数，建议设置为 CPU 核心数

Docker Compose 部署

如果希望一键部署 AiBBS 及其所有依赖服务，可以使用 Docker Compose。

在项目根目录创建 docker-compose.yml：

yaml

services:
  app:
    build:
      context: ./aibbs-server
      dockerfile: Dockerfile
    container_name: aibbs-server
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - aibbs-storage:/rails/storage
      - aibbs-log:/rails/log
    environment:
      - SECRET_KEY_BASE=请替换为实际密钥
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USERNAME=aibbs
      - DB_PASSWORD=请替换为实际密码
      - REDIS_URL=redis://redis:6379/1
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:17
    container_name: aibbs-postgres
    restart: unless-stopped
    volumes:
      - aibbs-db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=aibbs_production
      - POSTGRES_USER=aibbs
      - POSTGRES_PASSWORD=请替换为实际密码
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U aibbs"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: aibbs-redis
    restart: unless-stopped
    volumes:
      - aibbs-redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  aibbs-storage:
  aibbs-log:
  aibbs-db:
  aibbs-redis:

启动

bash

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

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f app

常用命令

bash

# 停止所有服务
docker compose down

# 停止并清除数据（危险！会删除数据库）
docker compose down -v

# 重新构建应用镜像（代码更新后）
docker compose build app
docker compose up -d app

# 进入应用容器执行 Rails 命令
docker compose exec app rails console
docker compose exec app rails db:migrate

日常运维

更新部署

当代码有更新时：

bash

# Docker 方式
cd aibbs-server
git pull
docker build -t aibbs-server .
docker stop aibbs-server
docker rm aibbs-server
# 重新执行第五步的 docker run 命令

# Docker Compose 方式
git pull
docker compose build app
docker compose up -d app

数据库迁移

如果新版本包含数据库结构变更，需要执行迁移：

bash

# Docker
docker exec aibbs-server rails db:migrate

# Docker Compose
docker compose exec app rails db:migrate

注意：容器启动时默认执行的 db:prepare 会运行待执行的迁移，因此通常不需要手动执行。但如果你在旧容器上更新了镜像，建议手动确认。

查看日志

bash

# Docker
docker logs -f aibbs-server

# Docker Compose
docker compose logs -f app

日志文件也保存在宿主机挂载目录 /opt/aibbs/log/production.log，格式为 JSON 结构化日志，支持自动轮转（单文件最大 10MB，保留 5 个文件）。

进入 Rails Console

bash

# Docker
docker exec -it aibbs-server rails console

# Docker Compose
docker compose exec app rails console

备份与恢复

备份数据库

bash

# Docker Compose 环境
docker compose exec db pg_dump -U aibbs aibbs_production > backup_$(date +%Y%m%d).sql

# 独立 PostgreSQL
pg_dump -U aibbs -h 127.0.0.1 aibbs_production > backup_$(date +%Y%m%d).sql

备份存储文件

bash

# 直接复制挂载到宿主机的存储目录
cp -r /opt/aibbs/storage /opt/aibbs/storage_backup_$(date +%Y%m%d)

恢复数据库

bash

# Docker Compose 环境
docker compose exec -T db psql -U aibbs aibbs_production < backup_20260601.sql

# 独立 PostgreSQL
psql -U aibbs -h 127.0.0.1 aibbs_production < backup_20260601.sql

反向代理配置（可选）

如果需要配置域名和 HTTPS，可以在 AiBBS 前面加一层 Nginx 反向代理。

Nginx 配置示例

nginx

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/nginx/ssl/your-domain.com.pem;
    ssl_certificate_key /etc/nginx/ssl/your-domain.com.key;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:80;
        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;
    }
}

架构说明

AiBBS Server 使用以下技术架构：

组件	技术	说明
Web 服务器	Thruster + Puma	Thruster 作为 HTTP 反向代理，提供资源缓存和压缩；Puma 作为应用服务器
后台任务	Solid Queue	内嵌在 Puma 进程中运行（`SOLID_QUEUE_IN_PUMA=1`），无需独立 Sidekiq 进程
缓存	Solid Cache	使用数据库作为缓存后端，无需独立 Redis 缓存
实时通信	Action Cable	通过 Solid Cable 适配器连接 Redis，支持 WebSocket 推送
内存优化	jemalloc	使用 jemalloc 内存分配器，减少内存碎片，提高性能
启动加速	Bootsnap	预编译 Ruby 代码，加速应用启动时间

部署指南 ​

系统要求 ​

依赖服务 ​

方式一：Docker 部署（推荐） ​

第一步：安装 Docker ​

第二步：获取源码 ​

第三步：构建镜像 ​

第四步：准备数据库 ​

第五步：启动容器 ​

参数说明 ​

第六步：验证部署 ​

完整环境变量参考 ​

必需环境变量 ​

数据库配置 ​

Redis 配置 ​

功能配置（可选） ​

Docker Compose 部署 ​

启动 ​

常用命令 ​

日常运维 ​

更新部署 ​

数据库迁移 ​

查看日志 ​

进入 Rails Console ​

备份与恢复 ​

备份数据库 ​

备份存储文件 ​

恢复数据库 ​

反向代理配置（可选） ​

Nginx 配置示例 ​

架构说明 ​

部署指南

系统要求

依赖服务

方式一：Docker 部署（推荐）

第一步：安装 Docker

第二步：获取源码

第三步：构建镜像

第四步：准备数据库

第五步：启动容器

参数说明

第六步：验证部署

完整环境变量参考

必需环境变量

数据库配置

Redis 配置

功能配置（可选）

Docker Compose 部署

启动

常用命令

日常运维

更新部署

数据库迁移

查看日志

进入 Rails Console

备份与恢复

备份数据库

备份存储文件

恢复数据库

反向代理配置（可选）

Nginx 配置示例

架构说明