Skip to content

getting started

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

本地运行与首次安装

目标是运行一个没有业务插件的 SandAdmin 宿主，完成 PostgreSQL 初始化并登录后台。适用公开 SandAdmin 0.2.1（Sand Core 0.2.2、SandPackage 0.2.2）；已有实例升级见部署与升级，不重新执行安装。

准备环境

需要 Git、Composer、PHP ≥8.2、PDO PostgreSQL 驱动，以及 Node.js 22 系列（至少 22.12.0）和 pnpm 11.19.0。前端 packageManager 固定 pnpm@11.19.0；请使用这一版本读取项目现有锁文件，不改锁文件来兼容旧工具。Windows 已实测 Node.js 22.23.3 与 pnpm 11.19.0；其他工具组合应另行验证。生产环境应记录实际工具版本并使用项目锁文件。PostgreSQL 的最低服务端版本未在宿主依赖中声明，不应凭文档推定任意版本兼容。

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

先查看工具与驱动：

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

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

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

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

git clone https://github.com/supdger/sandadmin.git
cd sandadmin
git checkout 0.2.1
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。保持前端终端运行；端口被占用时启动会明确失败，不再自动换到其他端口。先查看占用进程；若属于其他应用，保留它并在前端 .env.development.local 中设置一个已确认空闲的 VITE_PORT，重启前端后重新打开安装页，让页面读取同一配置。若确实是自己不再需要的旧前端进程，在确认进程身份后停止该准确PID。开发代理把 /api 转发至 http://127.0.0.1:8787 并移除 API 前缀。若后端端口不同，修改 .env.development 中的 VITE_API_PROXY_URL。配置详情见配置参考。

若 Windows 报端口占用，可在 PowerShell 核对进程后决定是否停止（修改端口时，把下方3006换为实际配置值）：

$listener = Get-NetTCPConnection -LocalPort 3006 -State Listen
Get-Process -Id ($listener.OwningProcess | Sort-Object -Unique)
# 仅确认这些PID是自己不再需要的前端进程后执行；提示时再次确认
Stop-Process -Id ($listener.OwningProcess | Sort-Object -Unique) -Confirm

不要批量停止 Node/PHP 或杀死所有占用端口的程序。锁文件检查失败时先核对 Node/pnpm 版本和下载revision，保留原错误输出；不要删锁文件、复制其他项目的node_modules或在部署时默默更新依赖。

完成安装并进入后台

  1. 打开后端 /core/install，填入此前准备的 PostgreSQL 连接信息。
  2. 明确确认初始化空数据库后提交。该动作执行SQL并生成数据库配置及 .env，按实际进程模式完成后端重载。
  3. 完成页保留“安装成功”及当次初始凭据，并检查管理端专属静态资源。前端尚未运行时，仍停留在完成页；按页面步骤启动前端后点“重新检查”，再点“进入管理后台”。
  4. 在真实登录页使用新库的 admin / 123456 登录，立即修改密码，确认系统菜单与用户信息正常加载。静态资源响应不表示登录、认证或业务验收成功。

安装后刷新或重新访问 /core/install 仍可检查和恢复后台入口，不会重新初始化数据库，也不会再次显示初始密码。已有实例保留 .env，不要删除它绕过安装保护。页面提供的“使用其他后台地址 / 手工核验”可临时更正入口；“尚未确认”的手工入口由用户主动选择，不代表自动检查通过。

后台部署在独立域名或子路径

部署管理员在后端进程的环境中设置 SANDADMIN_FRONTEND_URL，例如 https://admin.example.com/ 或同源 /admin/；后端重载环境后该地址优先于开发端口。已安装宿主可在 server/.env 增加这一配置并按现有运行方式重载后端；新实例不要为此提前创建 server/.env，可在启动终端中设置环境变量：

$env:SANDADMIN_FRONTEND_URL = 'https://admin.example.com/'
php windows.php

macOS/Linux 在后端 server/ 终端中可使用 SANDADMIN_FRONTEND_URL='https://admin.example.com/' php start.php start。同源路径相对于安装页的协议、域名和端口。地址仅支持HTTP(S)或以单个 / 开头的同源路径，不在URL中放账号、密码、访问密钥或含凭据查询参数。页面把入口指向登录路由，不替代前端静态站点与API反向代理配置；生产运行无需开启开发Vite服务器，详见部署。

检查读取前端的专属静态图像，不执行前端应用或登录API。旧构建缺失图像、HTTPS混合内容、CSP的 img-src 或浏览器网络策略都可能导致“无法确认”，不能据此断言服务未启动。先核对实际URL及匹配构建，保持安全策略；确需自行核验时使用明确标记为尚未确认的手工入口。

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

附加到已有 Webman

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

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

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

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

后台系统更新

适用于安装 SandPackage 0.2.1 或更高版本、Core 0.2.0 或更高版本的 Linux/macOS 宿主。超级管理员从「插件管理 → 系统更新」查看宿主核心和插件管理器版本，选择目标版本，先检查，再确认升级。任务会保存进度，刷新或重连后可以续看；失败时先查看任务的恢复入口。Windows 后台执行需先通过正常 Composer 安装接入 SandPackage 0.2.2，在宿主 server/ 使用 composer require supdger/sand-package:^0.2.2 --with-all-dependencies 并保留安装钩子，核对锁文件及实际安装版本。旧公开版本不能直接获得此能力；普通 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。Windows 需 PHP CLI ≥8.2 与 proc_open，无需 pcntl/posix，执行器固定通过 SystemRoot/System32/WindowsPowerShell/v1.0/powershell.exe 定位 Windows PowerShell 5.1。健康检查应核对真实 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

    Windows 在宿主 server/ 的 PowerShell 中执行，替换为自己的实际路径：

    & 'C:/tools/php/php.exe' vendor/supdger/sand-package/tools/prepare-system-update.php --frontend='D:/sandadmin/sandadmin-artd' --static='D:/sandadmin/server/public/admin'

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

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

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

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

Windows 固定命令与运行条件

Windows 后台更新使用本地盘符目录；UNC、设备路径、盘符相对路径、路径别名及 reparse point（包括 junction）会拒绝。复制包内配置示例后，用宿主现有绝对路径逐项替换，例如：

'php' => 'C:/tools/php/php.exe',
'composer' => ['C:/tools/php/php.exe', 'C:/tools/composer/composer.phar'],
'pnpm' => ['C:/Program Files/nodejs/node.exe', 'C:/tools/pnpm/bin/pnpm.cjs'],
'reload' => ['C:/tools/php/php.exe', 'D:/sandadmin/ops/reload.php'],
'health' => ['C:/tools/php/php.exe', 'D:/sandadmin/ops/health.php'],

命令是固定 argv，首项必须为原生 .exe。不能直接填 composer.bat、pnpm.cmd、shell 字符串、&& 或管道；找到宿主实际 Composer PHAR 和 pnpm JavaScript 入口，不把示例安装位置当成自动发现结果。现有维护脚本若为 PowerShell，可配置 [getenv('SystemRoot') . '/System32/WindowsPowerShell/v1.0/powershell.exe', '-NoLogo', '-NoProfile', '-NonInteractive', '-File', 'D:/sandadmin/ops/reload.ps1']，健康脚本用相同形式。执行器不创建服务脚本；重载须操作真实服务，健康检查须验证真实 HTTP 与预期版本，失败返回非零状态。

实现最低条件为 Windows 8 / Server 2012 及以上与 Windows PowerShell 5.1，本次原生验收环境为 Windows 10、PHP 8.2.12、Windows PowerShell 5.1；最低条件不等于全部 Windows 版本或服务部署方式均已实测。服务账户须允许独立后台进程脱离宿主进程作业；禁止脱离时会明确报告启动失败。

任务独立运行并保存阶段记录；Windows 更新命令由进程作业管理，超时或执行器退出会结束所属子进程树。查询进度暂时占用记录时，保存有限重试；持续占用仍保留原记录并报告失败。失败后保留任务及备份，先使用任务恢复入口。原生定向验收覆盖独立执行、进程终止与恢复等行为，不代表已有生产服务已升级或完成登录业务验收。

开始使用

基础包参考

开发插件

版本更新

版本和维护

Clone this wiki locally