getting started

本地运行与首次安装

目标是运行一个没有业务插件的 SandAdmin 宿主，完成 PostgreSQL 初始化并登录后台。适用公开源码主线 276c89e188c5346df8535eb9b90608f189a3e572；已有实例升级见部署与升级，不重新执行安装。

准备环境

需要 Git、Composer、PHP ≥8.2、PDO PostgreSQL 驱动，以及 Node.js 22 系列（至少 22.12.0）和 pnpm 9.15.9。本指南选择这一组合以满足锁定 Vite 7.1.7 的 Node 要求和 pnpm v9 锁文件格式；这是兼容要求核查，不表示该组合已经完成运行验收。生产环境应记录实际工具版本并使用项目锁文件。PostgreSQL 的最低服务端版本未在宿主依赖中声明，不应凭文档推定任意版本兼容。

由数据库管理员事先准备空数据库、连接地址、端口、库名、用户和密码；数据库用户须能创建安装所需表和 ORM 元数据函数。安装器不创建数据库。数据库写入及本机服务启动应由环境所有者安排。

先查看工具与驱动：

php -v
php --ri pdo_pgsql
composer --version
node --version
pnpm --version

任一命令失败先修复对应 CLI 环境；不要以修改依赖锁文件替代环境准备。安装好 Node.js 22 系列后，可执行 npm install --global pnpm@9.15.9 准备本指南使用的 pnpm，再运行 pnpm --version 确认版本。全局安装权限按自己的 Node.js 安装方式处理。

1. 获取固定源码并安装后端依赖

以下 Git 命令适用于 macOS/Linux 终端及 Windows PowerShell，在准备存放项目的目录执行：

git clone https://github.com/supdger/sandadmin.git
cd sandadmin
git checkout 276c89e188c5346df8535eb9b90608f189a3e572
cd server
composer install
composer check-platform-reqs

Composer 应成功结束并安装锁文件中的基础包。检查 vendor/autoload.php、plugin/sandadmin/、plugin/sandpackage/ 是否存在。不要用 composer update 代替锁定版本安装。Composer 发布源码不等于数据库初始化或前端构建。

全新实例此时不要复制 server/.env.example 为 .env：安装器发现 .env 会显示“程序已经安装”。已有实例保留原 .env，不要删除它来绕过安装保护。

2. 启动后端

在 server/ 保持终端运行。

macOS/Linux：

php start.php start

Windows PowerShell：

php windows.php

Windows 入口为仓库提供的多进程启动脚本，与 Unix 的后台进程管理方式不同；Windows 启动的实际验证范围见版本范围。正常情况下终端显示进程启动信息，浏览器访问 http://127.0.0.1:8787/core/install 应显示安装页。若端口或权限报错，见排障。

3. 启动管理前端

另开终端，进入项目根目录下的 sandadmin-artd/。macOS/Linux：

cp .env.example .env
cp .env.development.example .env.development
pnpm install --frozen-lockfile
pnpm run dev

Windows PowerShell：

Copy-Item .env.example .env
Copy-Item .env.development.example .env.development
pnpm install --frozen-lockfile
pnpm run dev

默认端口为 3006，以 Vite 实际输出地址为准。开发代理把 /api 转发至 http://127.0.0.1:8787 并移除 API 前缀。若后端端口不同，修改 .env.development 中的 VITE_API_PROXY_URL。配置详情见配置参考。

锁文件检查失败时保留错误输出，先确认 pnpm 为本指南的 9.15.9：pnpm 8 不兼容此处 lockfileVersion: 9.0。再核对是否下载了同一 revision 的 package.json 与锁文件；不要删除锁文件或在部署时默默更新依赖。Corepack 签名错误的处理见排障。

4. 完成安装并登录

1. 打开后端 /core/install，填入此前准备的 PostgreSQL 连接信息。
2. 明确确认初始化空数据库后提交。该动作执行 SQL、生成数据库配置及 .env，并可能向 Unix 父进程发送 reload 信号。
3. 安装成功后到前端登录页，使用新库的 admin / 123456 登录，立即修改密码。已有实例不会被此说明重置密码。
4. 检查系统菜单与用户信息正常加载。只有登录和实际页面通过后，才能记录基础运行成功。

若页面报错，先保存页面信息和 server/runtime/logs/ 中的相关日志，避免反复初始化。下一步是插件安装或部署。

附加到已有 Webman

标准 Webman 项目可以安装基础包：

composer require supdger/sand-core
composer require supdger/sand-package

仅需核心时省略第二条。上述未指定版本的命令由 Composer 选择兼容可用版本，不保证得到本 Wiki 核查的 0.1.8/0.1.9；安装后以自己的 composer.lock 为准。项目须保留 support\Plugin::install 的 post-package-install、post-package-update 钩子。后端发布到 plugin/，前端目录的放置规则由所选包负责。执行前备份已有配置及前端修改，发生冲突时先检查包安装器与清单，不强行覆盖。

来源：宿主依赖、前端要求、Windows 入口、核心安装器。实际目标环境的安装与登录结果应按版本范围记录。