安装过程
Docker 环境启动后,通过 Drupal 安装向导完成 Drubase One 的安装配置。
🌐 访问安装向导
打开浏览器
访问 http://YOUR_HOST (如果修改了端口,使用对应端口如 http://YOUR_HOST:8080)
您将看到 Drupal 安装向导的欢迎页面。
📝 安装步骤
步骤 1: 选择语言
- 默认语言: 简体中文 (zh-hans)
- 也可以选择 English
点击 继续 或 Continue
步骤 2: 选择安装配置文件
重要: 必须选择 Baas Platform 配置文件
- ✅ Baas Platform - Drubase One 后端即服务平台
- ❌
标准- 不要选择标准安装 - ❌
最小化- 不要选择最小化安装
选择 Baas Platform 后点击 继续
步骤 3: 配置数据库
填写数据库连接信息:
| 配置项 | 值 |
|---|---|
| 数据库类型 | PostgreSQL |
| 数据库名 | drubase |
| 数据库用户名 | postgres |
| 数据库密码 | baas_password (或您在 .env 中设置的密码) |
| 高级选项 | 点击展开 |
| 主机 | pg17 (容器名) |
| 端口 | 5432 |
重要提示:
- 主机名使用 容器名
pg17,不是localhost - 这是因为服务之间通过 Docker 网络通信
点击 继续
步骤 4: 安装模块和演示数据
系统会自动执行以下操作:
-
安装 Drupal 核心 (约 1-2 分钟)
-
安装 BaaS 模块 (约 30 秒):
- baas_tenant (租户管理)
- baas_entity (动态实体)
- baas_api (API 接口)
- baas_auth (认证授权)
- baas_project (项目管理)
- baas_file (文件管理)
- baas_realtime (实时功能)
- baas_functions (函数服务)
-
导入演示数据 (约 1 分钟):
- ✅ 系统用户 (admin, user1, user2)
- ✅ Groups Sports 演示租户
- ✅ Groups Sports 演示项目
- ✅ 动态实体模板 (users, activities, teams, positions)
- ✅ 示例业务数据 (3 个用户, 1 个活动, 4 个球队, 24 个位置)
- ✅ 上传文件 (头像和球队 Logo)
- ✅ 权限和角色配置
进度指示器:
正在安装 Drupal... ████████░░ 80%
正在安装 BaaS 模块... ██████████ 100%
正在导入演示数据... ██████████ 100%步骤 5: 配置站点信息
填写基本站点信息:
| 配置项 | 建议值 |
|---|---|
| 站点名称 | Drubase One |
| 站点电子邮件 | admin@example.com |
| 用户名 | admin |
| 密码 | 使用强密码 (至少 12 位) |
| 确认密码 | 重复密码 |
| 电子邮件地址 | admin@example.com |
密码要求:
- 至少 12 个字符
- 包含大小写字母
- 包含数字
- 包含特殊字符
点击 保存并继续
步骤 6: 完成安装
安装成功后,您会看到:
🎉 Drubase One 安装成功!
您的 BaaS 平台已就绪。
演示项目 "Groups Sports" 已自动导入。点击 访问您的新站点 进入管理后台。
步骤 7: 配置缓存设置
安装完成后,需要配置 Redis 缓存和渲染缓存设置以确保最佳性能和正确的缓存行为。
进入 PHP 容器
docker exec -it php8-4-fpm sh
cd /var/www/html编辑 settings.php
使用 vi 或其他编辑器打开配置文件:
vi web/sites/default/settings.php添加 Redis 缓存配置
在文件末尾添加以下配置:
/**
* Redis 缓存配置
*/
$settings['redis.connection']['interface'] = 'PhpRedis';
$settings['redis.connection']['host'] = 'redis';
$settings['cache']['default'] = 'cache.backend.redis';
/**
* 渲染缓存使用内存后端
*
* 这确保页面渲染缓存不会被持久化到 Redis,
* 避免创建/更新数据后需要手动清除缓存才能看到变化的问题。
*/
$settings['cache']['bins']['render'] = 'cache.backend.memory';
$settings['cache']['bins']['page'] = 'cache.backend.memory';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.memory';配置说明:
| 配置项 | 说明 |
|---|---|
redis.connection.interface | 使用 PhpRedis 扩展 (比 Predis 性能更好) |
redis.connection.host | Redis 容器名称 |
cache.default | 默认缓存使用 Redis |
cache.bins.render | 页面渲染缓存使用内存 |
cache.bins.page | 完整页面缓存使用内存 |
cache.bins.dynamic_page_cache | 动态内容缓存使用内存 |
为什么这样配置?
- ✅ 数据缓存使用 Redis - 配置、实体等数据缓存持久化,重启容器后保留
- ✅ 渲染缓存使用内存 - 页面渲染结果每次请求重新生成,确保数据变更立即可见
- ✅ 避免缓存问题 - 防止创建项目/实体后需要手动清缓存才能显示的问题
保存并退出
# vi 编辑器: 按 ESC 然后输入
:wq
# 或使用 nano 编辑器
# Ctrl+O 保存, Ctrl+X 退出重启 PHP 容器使配置生效
# 退出容器
exit
# 重启 PHP 容器
docker compose restart php8-4-fpm
# 清除所有缓存
docker exec php8-4-fpm sh -c "cd /var/www/html && vendor/bin/drush cr"验证 Redis 连接
# 检查 Redis 是否正常工作
docker exec php8-4-fpm sh -c "cd /var/www/html && vendor/bin/drush status"应该看到类似输出:
Drupal version : 11.x
Site URI : http://default
Database : Connected
Cache backend : Redis步骤 8: 配置域名(可选)
如果您需要使用自定义域名访问 Drubase One,需要修改以下配置文件。
⚠️ 重要提示:
- 默认配置使用
localhost访问,适合本地开发 - 如果使用自定义域名(如
drubase.example.com),必须修改以下两个文件 - 所有配置中的域名必须保持一致
1. 修改 docker/.env 文件
编辑 docker/.env 配置域名信息:
vi docker/.env找到并修改以下配置项:
# 域名配置
# BaaS平台内部域名(用于容器间通信)
# ⚠️ 如果需要自定义域名,请修改此变量,同时需要更新nginx vhost配置中的server_name
BAAS_DOMAIN=your-domain.com
# 外部访问域名(用于浏览器访问)
# ⚠️ 这是用户在浏览器中输入的域名
DOMAIN=your-domain.com配置说明:
| 配置项 | 默认值 | 说明 |
|---|---|---|
BAAS_DOMAIN | local.drubase.com | 内部服务通信域名,需与 Nginx 配置一致 |
DOMAIN | localhost | 外部访问域名,浏览器访问地址 |
示例配置:
# 示例 1: 本地开发(默认)
BAAS_DOMAIN=local.drubase.com
DOMAIN=localhost
# 示例 2: 使用自定义域名
BAAS_DOMAIN=api.example.com
DOMAIN=api.example.com
# 示例 3: 使用IP地址
BAAS_DOMAIN=192.168.1.100
DOMAIN=192.168.1.1002. 获取 API Key
在 Drubase One 后台生成 API Key:
1. 登录后台: http://YOUR_HOST/admin
2. 访问: http://YOUR_HOST/user/api-keys
3. 点击"创建新的 API Key"
4. 复制生成的 Key 并填入 runtime-config.js3. 重启服务使配置生效
修改配置后,必须重启相关服务:
# 重启所有服务
cd docker && docker compose restart
# 或者只重启受影响的服务
cd docker && docker compose restart nginx php8-4-fpm
# 清除缓存
docker exec php8-4-fpm sh -c "cd /var/www/html && vendor/bin/drush cr"4. 验证域名配置
# 测试 BaaS 平台访问
curl http://YOUR_DOMAIN/api/health
# 测试 Groups 应用访问
curl http://YOUR_DOMAIN:3000
# 如果使用自定义域名,确保 DNS 已正确解析
ping YOUR_DOMAIN💡 提示:
- 修改
docker/.env后需要重启 Docker 服务 - 修改
runtime-config.js后只需刷新浏览器即可生效 - 生产环境建议使用 HTTPS,需要额外配置 SSL 证书
- 详细的域名和 SSL 配置请参考 域名配置指南
✅ 验证安装
1. 检查系统状态
访问系统状态页面:
http://YOUR_HOST/admin/reports/status确认所有检查项都是绿色 ✅:
- PHP 版本: 8.4.x
- 数据库: PostgreSQL 17.x
- 文件系统: 可写
- Cron: 已配置
2. 验证 BaaS 模块
访问模块页面:
http://YOUR_HOST/admin/modules确认以下模块已启用:
- ✅ BaaS Tenant
- ✅ BaaS Entity
- ✅ BaaS API
- ✅ BaaS Auth
- ✅ BaaS Project
- ✅ BaaS File
- ✅ BaaS Realtime
- ✅ BaaS Functions
- ✅ BaaS Platform Demo Data
3. 验证演示数据
检查租户
docker exec -it pg17 psql -U postgres -d drubase -c "SELECT tenant_id, name, status FROM baas_tenant_config;"应该看到:
tenant_id | name | status
-----------------+------------------------+--------
tenant_7375b0cd | Groups Sports Demo | 1检查项目
docker exec -it pg17 psql -U postgres -d drubase -c "SELECT project_id, name FROM baas_project_config;"应该看到:
project_id | name
---------------------------------------+---------------------------
tenant_7375b0cd_project_6888d012be80c | Groups Sports Activity检查动态实体
docker exec -it pg17 psql -U postgres -d drubase -c "SELECT COUNT(*) FROM baas_856064_users;"应该返回: 3 (3 个示例用户)
4. 测试 API 接口
健康检查
curl http://YOUR_HOST/api/health应该返回:
{
"success": true,
"data": {
"status": "ok",
"timestamp": 1234567890,
"services": {
"database": "ok",
"redis": "ok",
"functions": "ok"
}
}
}获取租户信息
curl http://YOUR_HOST/api/tenant/tenant_7375b0cd应该返回租户详细信息。
5. 访问 API 文档
http://YOUR_HOST/swagger-ui查看完整的 RESTful API 文档和交互式测试界面。
🎯 默认账户
安装完成后,系统包含以下预置账户:
| 用户名 | 密码 | 角色 | 说明 |
|---|---|---|---|
| admin | (您设置的密码) | 超级管理员 | 安装时创建,拥有所有权限 |
| user1 | 888888 | 租户&项目所有者 | 演示账户,Groups 项目所有者 |
| user2 | 888888 | 项目成员 | 演示账户,普通成员 |
⚠️ 安全提示: 生产环境请立即修改所有默认密码!
📊 演示项目详情
Groups Sports 项目
演示项目包含一个完整的运动队伍管理系统:
租户信息:
- ID:
tenant_7375b0cd - 名称: Groups Sports Demo
- 状态: 活跃
项目信息:
- ID:
tenant_7375b0cd_project_6888d012be80c - 名称: Groups Sports Activity Management
- 描述: 智能团队运动平台演示
动态实体 (6 个):
- users - 用户实体 (3 条记录)
user1@drubase.com(密码: 888888)user2@drubase.com(密码: 888888)user3@drubase.com(密码: 888888)- 包含头像字段 (关联文件)
- activities - 活动实体 (1 条记录)
- teams - 球队实体 (4 条记录)
- 包含 Logo 字段 (关联文件)
- positions - 位置实体 (24 条记录)
- user_activities - 用户活动关系 (2 条记录)
- system_config - 系统配置
上传文件 (4 个):
- 用户头像: 2 个
- 球队 Logo: 2 个
- 总大小: ~635 KB
数据库表:
所有动态实体使用 baas_856064_ 前缀:
baas_856064_usersbaas_856064_activitiesbaas_856064_teamsbaas_856064_positionsbaas_856064_user_activitiesbaas_856064_system_config
🔍 故障排查
问题 1: 无法访问安装向导
症状: 浏览器显示 “无法访问此网站” 或连接超时
检查步骤:
# 1. 确认容器运行
docker compose ps
# 2. 检查 Nginx 日志
docker compose logs nginx
# 3. 测试端口
curl http://YOUR_HOST
# 4. 检查防火墙
sudo ufw status # Linux问题 2: 数据库连接失败
错误: “Failed to connect to your database server”
解决方案:
# 1. 验证数据库容器运行
docker compose ps pg17
# 2. 测试数据库连接
docker exec -it pg17 psql -U postgres -d drubase
# 3. 检查配置
# 主机名必须是容器名 "pg17" 而不是 "localhost"
# 端口是容器内部端口 5432
# 4. 检查密码
# 密码应与 docker-compose.yml 或 .env 中的 POSTGRES_PASSWORD 一致问题 3: 安装过程卡住
症状: 进度条长时间不动
解决方案:
# 1. 检查 PHP 日志
docker compose logs php8-4-fpm
# 2. 检查 PHP 内存限制
docker exec php8-4-fpm php -i | grep memory_limit
# 3. 增加内存限制 (如果需要)
# 编辑 docker/fpm/php.ini
memory_limit = 512M
# 4. 重启 PHP 容器
docker compose restart php8-4-fpm
# 5. 刷新浏览器继续安装问题 4: 演示数据导入失败
错误: 安装完成但没有演示数据
检查:
# 检查演示数据模块是否启用
docker exec php8-4-fpm sh -c "cd /var/www/html && vendor/bin/drush pm:list --type=module --status=enabled | grep demo"
# 应该看到: baas_platform_demo_data手动导入:
# 进入 PHP 容器
docker exec -it php8-4-fpm sh
cd /var/www/html
# 启用演示数据模块 (会自动触发导入)
vendor/bin/drush en baas_platform_demo_data -y
# 清除缓存
vendor/bin/drush cr问题 5: 权限错误
错误: “The directory sites/default/files is not writable”
解决方案:
# 进入 PHP 容器
docker exec -it php8-4-fpm sh
# 修复权限
cd /var/www/html
chown -R www-data:www-data web/sites/default/files
chmod -R 755 web/sites/default/files
# 创建目录 (如果不存在)
mkdir -p web/sites/default/files
chown www-data:www-data web/sites/default/files🔒 安装后安全检查
1. 修改默认密码
# 登录后台
# 访问: http://YOUR_HOST/user/1/edit
# 修改 admin 密码
# 修改演示账户密码 (user1, user2)2. 删除安装文件 (生产环境)
docker exec -it php8-4-fpm sh
cd /var/www/html
rm -f web/install.php3. 配置 Trusted Host Patterns
编辑 web/sites/default/settings.php:
$settings['trusted_host_patterns'] = [
'^localhost$',
'^127\.0\.0\.1$',
'^your-domain\.com$', // 添加您的域名
];4. 启用 HTTPS (生产环境)
配置 SSL 证书和 HTTPS 重定向。
➡️ 下一步
安装完成后,继续: