PowerX 文档中心

简体中文

English

简体中文

English

Appearance

本地开发启动 ​

这篇教程直接在自己的电脑运行 Go 后端和 Node.js 管理后台，完成首次 Setup，并用自己创建的管理员登录。不需要安装 Docker，也不使用 XDocker。

起点：一台开发电脑，一个全新目录。终点：http://127.0.0.1:3030 可以登录，后端安装状态为 installed。

1. 检查工具 ​

适用 macOS 或 Linux，使用 Bash 终端。本页假设开发工具、PostgreSQL 和 Redis 已安装，只说明如何连接并启动 PowerX，不展开环境安装。使用本地文件存储，不需要 MinIO。

工具本教程使用的版本／要求
Git、Make、curl、OpenSSL系统可执行命令
Go1.26.7，与本次源码 backend/go.mod 一致
Node.js22.23.2，使用随附的 npm
数据服务可连接的 PostgreSQL 16 + pgvector、Redis 7；可以是已有服务
不确定工具版本？展开检查

在本机终端 A执行：

bash
bash
set -eu
git --version
make --version
go version
node --version

看到 Go 1.26.7、Node v22.23.2，且其他工具没有报错即可。

以下命令在本机 Bash 终端运行；不要用 sudo 运行整个开发项目。

2. 获取最新 Release 的源码 ​

页面会自动获取最新可用容器 Release（含预发布），显示实际版本与发布时间。点击“复制克隆命令”，在本机终端 A粘贴执行；~/powerx-local 必须是新目录，不覆盖已有实例。这里只获取源码，不下载镜像，也不需要运行版本解析脚本。

最新可用容器 Release

正在从 GitHub 获取最新发布信息（含预发布）…

官方 Releases ↗

克隆成功后进入目录：

bash
cd ~/powerx-local

复制时选中的版本会固定在这次源码目录中；以后打开页面或点击“重新获取”，会重新查询。获取失败时不会提供旧版命令；可以重试，或从“官方 Releases”查看发行信息。

3. 确认数据库与缓存可连接 ​

已有服务直接用，不需要另建容器。 准备一个仅供本次开发使用的空数据库和账号，确认安装了 pgvector；再准备可使用的 Redis 连接。不要把测试迁移连到客户或正式数据库。

需要记下：数据库主机、端口、库名、用户名、密码，以及 Redis 主机、端口、密码。以下默认用本机 PostgreSQL 127.0.0.1:5432、数据库／账号 powerx，Redis 127.0.0.1:6379。使用其他连接时，下面的检查和 Setup 要同步替换；Redis 还需写入步骤 4 配置。远程服务通过已有可信内网或隧道连接，不为本教程开放数据库公网端口。

已有连接不确定是否可用？展开检查

在本机终端 A检查连接，按提示输入对应密码：

bash
psql -h 127.0.0.1 -p 5432 -U powerx -d powerx -W \
  -c "SELECT current_user, extversion FROM pg_extension WHERE extname='vector';"
redis-cli -h 127.0.0.1 -p 6379 --askpass ping

通过条件：第一条返回 powerx 和 vector 版本，第二条返回 PONG。已有本机 Redis 未设密码时，去掉 --askpass 再执行，并在后续配置中保持空字符串。psql／redis-cli 使用已有 PostgreSQL／Redis 附带的客户端。缺少服务或扩展时，先由自己的环境维护者补齐，不需要为了这篇教程安装 Docker。

本教程需要 PostgreSQL 和 Redis；MinIO、Kafka、RabbitMQ 和 NATS 不需要安装。

4. 准备自己的运行配置 ​

在本机终端 A执行：

bash
cd ~/powerx-local
test ! -e backend/etc/config.yaml
cp backend/etc/config_example.yaml backend/etc/config.yaml
chmod 600 backend/etc/config.yaml
openssl rand -hex 32

最后一条生成上传签名密钥；数据库与 Redis 使用步骤 3 已验证的连接与密码。将值保存到密码管理器，不要提交到 Git 或发送到聊天中。

用编辑器打开 backend/etc/config.yaml，修改已有字段，勿在文件末尾追加同名段落：

先改这几项，其余保留开发模板默认值：

要填的内容配置位置
已有 Redis 连接cache 下的 host、port、password；queue.redis.addr 填同一 主机:端口
仅本机监听 gRPCserver.grpc.host: 127.0.0.1
本地文件访问地址storage.local.public_base_url: http://127.0.0.1:8077/media
刚生成的上传签名密钥storage.local.upload_token_secret

数据库连接稍后在 Setup 填写，不必先手工写 YAML。当前 Setup 的 Redis 连接测试不会把 Redis 值写回运行配置，所以这里仍需填写 cache；不能只凭连接测试成功就跳过它。其余三处 Redis 密码保留模板空值，启动时会继承 cache.password，不用重复填写。如果 Redis 不是本机 6379，还需把 event.fabric.redis_addr、event.fabric.authorization.redis_addr 改为同一个实际地址。

哪些默认值不用改？

本次开发模板已使用 deployment.env: dev、后端 127.0.0.1:8077、database.dsn: ""、本机数据库 ssl_mode: disable、Redis DB 0、storage.default_driver: local、文件目录 ./storage/media 和 install.status: uninstalled。

auth.jwt_secret、server.secret_key 保持空，下一步自动生成。保留允许 http://127.0.0.1:3030 的 http_security.web_admin_origins。不需要填写 S3／MinIO 示例凭据。远程数据库的 TLS 配置需按现有连接要求填写，不能照搬本机的 disable。

5. 初始化密钥并安装前端依赖 ​

仍在本机终端 A，源码根目录执行：

bash
make init-secrets CONFIG=backend/etc/config.yaml
npm --prefix web-admin ci

首次会下载 Go／Node 依赖。通过条件：密钥初始化输出 generated（再次执行为 existing），npm 安装成功。命令不会打印 JWT 或服务加密密钥。

此时还没有完成安装，也没有管理员。不要执行 make seed、make db-refresh，也不要手改为 installed。 接下来后端先进入无需连接数据库的 Setup 模式，由向导连接数据库、迁移表结构并收集管理员信息；不需要先执行 make migrate。

6. 分别启动后端和管理后台 ​

本机终端 A：

bash
cd ~/powerx-local
POWERX_ENV=dev make dev

保持它运行，看到服务就绪后，打开本机终端 B：

bash
cd ~/powerx-local
POWERX_ENV=dev npm --prefix web-admin run dev -- --host 127.0.0.1 --port 3030

看到 Nuxt 显示 http://127.0.0.1:3030 后继续。本教程显式指定 3030；不要把 Nuxt 默认端口或 systemd-dev 的 3001／8081 混进来。

7. 完成首次 Setup ​

在本机浏览器打开 http://127.0.0.1:3030/setup。按页面顺序填写：

  1. 系统检查与许可：确认许可，部署环境选 dev。
  2. 数据库与基础配置：数据库类型 PostgreSQL、版本 16、主机 127.0.0.1、端口 5432、库名和用户均为 powerx；密码使用步骤 3 已验证的 PostgreSQL 密码。Redis 主机 127.0.0.1、端口 6379、索引 0，填 Redis 密码。两项连接测试成功后再继续。文件存储选 local，目录 ./storage/media（把默认 /data/uploads 改成这个开发目录）。
  3. 域名与 HTTPS：系统域名填 127.0.0.1:3030，不带协议；HTTPS 选关闭。后端端口 8077，管理端端口 3030。
  4. 管理员与租户：填写你自己的管理员用户名、邮箱、强密码和租户信息。这是以后登录使用的账号，与数据库密码无关。
  5. 插件与智能体：首次先保留默认选择；本教程不把额外插件或真实 AI 调用作为首装前置。
  6. LLM：可以选择跳过，安装后再配置模型。点击“完成设置”。

出现“安装已完成，请重启后端”时，在终端 A 按 Ctrl+C，重新执行步骤 6 的后端启动命令，再回页面点击“我已重启，立即检测”。若后端已经自动恢复，也先完成下一步状态验证。

8. 登录并确认结果 ​

打开 http://127.0.0.1:3030，使用刚设置的管理员账号登录。然后在另一个本机终端执行：

bash
curl -fsS http://127.0.0.1:8077/api/v1/health
curl -fsS http://127.0.0.1:8077/api/v1/admin/setup/status

完成条件：健康接口成功；状态响应的 data.install_status 为 installed、data.configured 为 true；刷新后台仍能进入自己的租户。restart_required 为 true 时按提示重启并复查端口。

开发结束时，在后端和前端终端按 Ctrl+C，已有数据服务不随开发项目停止。保留数据库数据、私有 config.yaml、原密钥和 backend/storage/。再次开发只需确认依赖可连接并执行步骤 6，不重新首装。

遇到问题 ​

现象先检查什么
Go 的 Sonic／ABI 编译错误确认实际使用 Go 1.26.7；不要用旧 Go 编译这个快照
数据库／Redis 连接失败重新执行步骤 3 的 psql／redis-cli 检查；核对服务是否运行、实际地址／端口和密码
打开 Setup 不代表安装完成按步骤 7 完成向导；不要用 seed 或改安装标志代替 Setup
Setup API 404 或页面连接失败核对后端 8077、前端 3030 和 POWERX_BACKEND；看终端 A、B 的日志
密钥无效／配置不可写确认启动日志读取的是本次 config.yaml，且归当前用户所有；已有实例恢复原密钥，勿删除配置重建

下一步：创建第一个插件 → 本地联调。

版本与源码依据

步骤 2 在浏览器中实时查询官方发布列表，按发布时间选择含完整容器包与校验文件的非草稿 Release，不限定标签前缀；预发布和未来的正式版本均可选中。查询失败或发布列表未能完整读取时不生成命令。后续工具版本、配置和启动步骤的源码核对基线仍为 PowerX f99333ccd80eb3c2467fe6cc9009917340556424；自动选中新版不代表本页已实测该版本，工具要求以所选源码的 backend/go.mod 和 web-admin/package.json 为准。核对来源包括 Make 迁移入口、开发配置与 Setup 实现。当前源码缓存工厂只注册 Redis，不能把 Setup 中其他缓存选项当成已实现的替代方案；核对了缓存工厂。这些链接用于查阅来源，不是完成本教程的必经步骤。本文命令经过源码静态核对，本次文档修订未重新执行全新机器安装。

基于 Apache 2.0 许可发布