Skip to content

getting started

Jump to bottom
supdger edited this page Oct 3, 2026 · 5 revisions

本地运行与首次安装

目标是运行一个没有业务插件的 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 入口、核心安装器。实际目标环境的安装与登录结果应按版本范围记录。

后台系统更新

适用于安装 SandPackage 0.2.1 或更高版本、Core 0.2.0 或更高版本的 Linux/macOS 宿主。超级管理员从「插件管理 → 系统更新」查看宿主核心和插件管理器版本，选择目标版本，先检查，再确认升级。任务会保存进度，刷新或重连后可以续看；失败时先查看任务的恢复入口。Windows 后台执行暂不支持，普通 ZIP 插件继续走原有插件仓库更新入口。

首次接入前由宿主管理员完成部署配置，不由页面猜测服务名称或重载方式：

  1. 备份现有配置及前端修改，在宿主 server/ 目录安装对应基础包。旧宿主若仍声明 Core 或 Package 为 ^0.1 系列约束，这些约束排除 0.2.0，不能只执行 composer update；使用正常 composer require supdger/sand-core supdger/sand-package --with-all-dependencies 重新选择可用稳定版本并更新约束，保持 support\Plugin::install 钩子启用。用 composer show 和自己的锁文件确认 Core 至少 0.2.0、Package 至少 0.2.1。首次接入先完成正常 Composer 安装，随后才有后台系统更新入口。

  2. 参考安装包内 vendor/supdger/sand-package/tools/system-update.config.example.php，在 server/config/sand_system_update.php 填写实际 PHP、前端源码、专用静态目录、Composer/pnpm 参数数组，以及宿主实际服务重载和运行健康检查命令。Linux/macOS PHP CLI 须支持 proc_open、pcntl 和 posix。健康检查应核对真实 HTTP 服务及预期版本，失败须返回非零状态。

  3. 按现有前端锁文件安装依赖并构建，将当前 dist 部署到填写的专用静态目录。目录与前端源码、宿主 app/config/vendor/plugin/runtime 分开。先确认部署内容与 dist 相同，再运行包内基线工具，使用自己的实际绝对路径：

    php vendor/supdger/sand-package/tools/prepare-system-update.php --frontend=/srv/sandadmin/sandadmin-artd --static=/srv/sandadmin/server/public/admin

    成功显示已核对的文件数量并建立静态清单；不一致会列出变化类型，先修正真实部署，不能伪造清单或强制覆盖。

  4. 在维护窗口内打开后台系统更新。预检核对本地文件、已安装插件兼容范围、磁盘空间及依赖；通过后确认，任务独立运行，完成备份、精确版本安装、前端发布构建、服务重载和健康检查。只在任务最终报告成功后确认更新完成。

仅官方稳定发行附带有效 system-update.json，并明确无数据库及宿主骨架变更时可选择。没有契约的旧发行不会列出；涉及数据库或宿主骨架变更的版本应按对应发行说明单独维护，不执行隐式迁移。首次 Composer 安装和现有实例真实升级是不同验收层。

任务中断时保留 server/runtime/system-update/jobs/<任务ID> 的记录、备份及固定执行器。自动恢复拒绝外部修改时，按 Package 使用说明 核对现场并执行人工确认恢复，恢复包含实际服务重载与健康检查，应在该宿主维护授权内进行。

开始使用

基础包参考

开发插件

版本更新

版本和维护

Clone this wiki locally