2.1 安装与初始化：把装配台搭起来
2.1 安装与初始化：把装配台搭起来
本节摘要：三条安装路线——Docker 镜像、CLI 脚手架、源码部署——分别对应「最快跑起来」「要开发插件」「要深度改内核」三种诉求。本节给出选路决策、每条路线的完整命令与预期输出、初始化向导的操作，以及装完必做的验证动作。
第 1 章把图纸看完了，现在动第一颗螺丝。安装是全流程里最容易卡住新手的一步，卡住的原因九成不是平台复杂，而是路线选错：想快点看到界面的人掉进了源码编译的坑，想开发插件的人却用镜像装了个黑盒。先把路选对。
领件清单：三条路线各自适配谁
图 2-1 安装路线决策图
三条路线装出的平台功能完全一致，区别只在可控程度：Docker 路线交付的是一个运行良好的黑盒，脚手架路线交付一个你能改的工程目录，源码路线交付整个仓库。选路原则一句话：离平台内部越近，维护责任越重。
二、Docker 路线：一条命令立起装配台
这条路线的零件只有两样：Docker 环境、一段启动命令。生产环境建议配合编排文件把数据库一起管起来，试验环境单容器即可。下面是带注释的最小启动命令，变量逐项说明：
docker run -d --name nocobase \ -e APP_KEY=change-me-to-a-random-string \ # 应用密钥，务必改成随机串，装完不可再改 -e DB_DIALECT=postgres \ # 数据库类型，试验用内置 PG 即可 -e DB_HOST=postgres \ # 数据库地址，单机试验可用容器内置库 -e DB_PORT=5432 \ -e DB_DATABASE=nocobase \ -e DB_USER=nocobase \ -e DB_PASSWORD=nocobase-password \ -e LOCAL_STORAGE_BASE_URL=http://localhost:13000 \ # 附件访问基础地址 -p 13000:80 \ # 宿主机端口映射，浏览器从这里进 nocobase/nocobase:latest
等待一两分钟后，浏览器访问宿主机映射端口（上面的例子是 13000），看到安装向导即成功。预期日志里能看到应用完成初始化、监听端口的过程；如果反复重启，第一件事是查数据库连接变量是否填对：
docker logs -f nocobase # 跟踪日志，直到看到应用就绪的输出 # 预期：出现数据库连接成功、插件加载、服务监听等日志行 # 常见报错：数据库连接被拒 → 检查 DB_HOST、DB_USER、DB_PASSWORD 三项
生产环境的做法是把容器与数据库写进编排文件统一管理，并显式挂载数据卷。下面给出编排文件的骨架（保存为编排配置后再启动，文件本身建议纳入版本管理）：
# docker-compose.yaml 骨架：应用 + 数据库 + 数据卷 services: app: image: nocobase/nocobase:latest environment: - APP_KEY=please-change-to-random - DB_DIALECT=postgres - DB_HOST=postgres - DB_DATABASE=nocobase - DB_USER=nocobase - DB_PASSWORD=strong-password ports: - "13000:80" depends_on: - postgres postgres: image: postgres:16 environment: POSTGRES_DB: nocobase POSTGRES_USER: nocobase POSTGRES_PASSWORD: strong-password volumes: - db-data:/var/lib/postgresql/data # 数据卷：容器重建后数据仍在 volumes: db-data:
⚠️ 常见坑：APP_KEY 装完后不可更改——它参与敏感数据的加密。装完才想起来没改？正确做法是备份配置、以新密钥重装、再恢复数据，而不是硬改环境变量。附件存储目录同样要纳入备份，丢了它，数据表还在、文件没了。
三、初始化向导与装后验收
首次访问会进入设置向导，依次完成管理员账号、界面语言、站点名称三件事。管理员密码当场存进密码管理器——它是你进入装配现场的唯一钥匙，丢了要走数据库层面的找回流程。完成后进主界面，做三个验收动作：点开「数据表」确认内置表在列；新建一个页面拖一个表格区块，确认界面装配可用；打开插件管理器确认插件清单加载完整。三个动作通过，装配台就算立住了。
CLI 脚手架路线只给要点：用脚手架命令创建应用工程，进入目录后安装依赖、启动开发服务，适合确定要写插件的团队；细节将在第 4 章的插件车间里连同插件脚手架一起展开。源码路线同样后置——在掌握前两条路线之前，不碰它。
装完之后的头一周：三件小事
装配台立住不等于万事大吉，头一周有三件小事值得立刻做。第一件，把编排文件、环境变量清单、管理员账号的存放位置写成一页「装机记录」——三个月后你一定会感谢这页纸，运维交接时它就是宪法。第二件，做首次备份演练：按 5.1 的三件套完整备一次，再恢复一次，确认链路通。第三件，升级预演：拉一次最新镜像到试验环境跑通启动，摸清「换件」的手感，第 5 章的升级工序就不再是纸上谈兵。
# 试验环境里的升级预演（不影响生产实例） docker pull nocobase/nocobase:latest # 提前拉镜像，避免窗口内干等 docker compose pull # 编排方式：整体刷新镜像 docker compose up -d # 以新镜像重建，观察启动日志 docker logs -f <容器名> # 就绪标志：迁移完成与插件加载完毕
这三件事的共同点是把「以后要做的正经事」提前变成「现在做过的熟事」。装机记录在交接时救场，备份演练在事故时救场，升级预演在版本日救场——头一周花掉的两三个小时，是全生命周期回报率最高的投入。
装配要点回顾
- 选路原则：离平台内部越近，维护责任越重；首例用 Docker，插件开发用脚手架，源码留给强定制团队；
- 密钥铁律：APP_KEY 与数据库口令在装机时一次定准，前者装后不可改；
- 数据两件套：数据库卷与附件目录必须纳入备份清单，缺一不可；
- 验收三动作：数据表在列、区块可拖、插件清单完整，全过才算装配台立住；
- 下一步：2.2 在这台刚立起来的台子上装配第一张业务数据表，客户管理案例正式开工。