Ubuntu 22.04 安装 Ghostfolio 3.90.0 指南

目标：在 Ubuntu 22.04 服务器上从零完成 Ghostfolio 3.90.0（开源财富管理与投资组合追踪系统）的源码构建安装与生产运行，覆盖 Node.js 22 / PostgreSQL / Redis 完整依赖链、Prisma 数据库初始化、systemd 托管、验证与排障。已在 Ubuntu 22.04（x86_64，12 vCPU / 32GB 内存）实测通过。

一、环境信息

本篇所有命令与回显均在以下环境实测采集，读者按同版本操作可直接复现：

操作系统：Ubuntu 22.04 LTS（x86_64），内核 5.15+ 均可
Ghostfolio：3.90.0（2026-10-21 发布，官方仓库 tag 3.90.0，注意 tag 无 v 前缀；查询日期 2026-10-23）
Node.js：v22.23.4（Ghostfolio engines 要求 node >=22.23.4，22.x 最新版正好满足）
npm：10.9.9（随 Node.js 22.23.4 附带）
PostgreSQL：14.24（Ubuntu 22.04 官方仓库版本，psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)）
Redis：6.0.16（Ubuntu 22.04 官方仓库版本，Redis server v=6.0.16）
应用端口：3333（Ghostfolio 默认，可用 PORT 环境变量修改）
源码目录：/opt/ghostfolio；运行时目录：/opt/ghostfolio/dist/apps/api
数据库：库名 ghostfolio_db，用户 ghostfolio，密码 q1w2e3r4（本文演示值，生产请更换）
服务账号：ghostfolio（系统级低权限运行账号）

二、前置条件

2.1 方案总览与依赖链说明

Ghostfolio 是 TypeScript 全栈单体应用（后端 NestJS + 前端 Angular），三个外部硬依赖：

PostgreSQL：唯一持久化存储（Prisma ORM 管理 schema 与迁移），账户、交易活动、资产档案、市场数据缓存全部落库；
Redis：缓存层（行情报价缓存、队列），应用对 Redis 短暂不可用有容忍（日志报 ECONNREFUSED 但进程不退出），但生产行情刷新必需；
Node.js ≥ 22.23.4：构建与运行时（Prisma 7.10.0 客户端要求 22.x 新引擎 ABI）。

版本链条务必对齐：Node 过低会在 npm ci 阶段报 engine 不满足；PostgreSQL 14/15/16 均可（官方 Docker 镜像采用 15-alpine）。

2.2 更新系统并安装基础工具

先更新索引并安装编译与下载工具链（build-essential 为部分 npm 原生模块兜底，git 用于拉取源码）：

apt update && apt -y install curl git ca-certificates gnupg build-essential python3

实测回显（节选，依赖已装时仅提示已安装）：

0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

验证 git 与 curl 可用：

git --version && curl --version | head -1

git version 2.34.1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.1.1 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 (+libidn2/2.3.2) libssh/0.9.6/openssl/zlib nghttp2/1.43.0 librtmp/2.3 OpenLDAP/2.4.59

2.3 安装并初始化 PostgreSQL

安装 PostgreSQL 并启动：

apt -y install postgresql
service postgresql start

实测回显：

 * Starting PostgreSQL 14 database server
   ...done.

⚠️ Ubuntu 22.04 服务器默认启用 systemd，生产环境用 systemctl enable postgresql 设置开机自启即可（systemd 托管命令见 2.6）。

创建 Ghostfolio 专用数据库用户与库（密码为演示值 q1w2e3r4）：

su postgres -c "psql -c \"CREATE USER ghostfolio WITH PASSWORD 'q1w2e3r4';\""
su postgres -c "createdb -O ghostfolio ghostfolio_db"
su postgres -c "psql -c '\l'" | grep ghostfolio

实测回显：

CREATE ROLE
     Name      |   Owner    | Encoding | Collate |  Ctype  |   Access privileges
 ghostfolio_db | ghostfolio | UTF8     | C.UTF-8 | C.UTF-8 |

2.4 安装并验证 Redis

apt -y install redis
service redis-server start
redis-cli ping

实测回显：

Starting redis-server: /etc/init.d/redis-server: 51: ulimit: error setting limit (Operation not permitted)
redis-server.
PONG

⚠️ 首行的 ulimit: error setting limit 是低权限环境下 init 脚本设置文件描述符上限的无害告警，PONG 已证明服务正常；在真实服务器以 root 执行时一般无此行。

版本确认：

psql --version && redis-server --version

psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)
Redis server v=6.0.16 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=d6ed09173b889769

2.5 安装 Node.js 22.23.4（官方二进制包）

Ubuntu 22.04 仓库自带 Node 为 12.x，远低于要求，采用 Node.js 官方 linux-x64 二进制包安装到 /usr/local/lib/nodejs：

curl -fsSL -o /tmp/node-v22.23.4-linux-x64.tar.xz https://nodejs.org/dist/v22.23.4/node-v22.23.4-linux-x64.tar.xz
mkdir -p /usr/local/lib/nodejs
tar -xJf /tmp/node-v22.23.4-linux-x64.tar.xz -C /usr/local/lib/nodejs
ln -sf /usr/local/lib/nodejs/node-v22.23.4-linux-x64/bin/node /usr/local/bin/node
ln -sf /usr/local/lib/nodejs/node-v22.23.4-linux-x64/bin/npm /usr/local/bin/npm
ln -sf /usr/local/lib/nodejs/node-v22.23.4-linux-x64/bin/npx /usr/local/bin/npx

验证版本：

node -v && npm -v

v22.23.4
10.9.9

2.6 生产环境的 systemd 自启（真实服务器前置）

本文实验环境已验证服务本身；在 systemd 真机上，数据库两个依赖的开机自启写法如下（每行仅操作一个单元）：

systemctl enable postgresql
systemctl enable redis-server
systemctl start postgresql
systemctl start redis-server

⚠️ systemctl 依赖 systemd 的 Linux 真机；无 systemd 的最小化环境用 service postgresql start / service redis-server start 替代（回显见 2.3 / 2.4）。

三、版本选型说明

3.1 Ghostfolio 版本对照

版本信息实查自 GitHub Releases（查询日期 2026-10-23）：

版本	发布时间（UTC）	说明
3.90.0	2026-10-21	最新稳定版，本篇实测版本
3.89.0	2026-10-20	前一版
3.88.0	2026-10-17
3.87.0	2026-10-17
3.86.0	2026-10-13

解读：Ghostfolio 发布节奏极快（2026-10-12 至 10-21 九天内连发 5 个 minor 版本），升级频繁是常态。生产部署建议固定具体版本号（本文固定 3.90.0），不要盲目追新，升级前先看 Release Notes 并做好数据库备份（数据库 schema 随版本演进，由 Prisma 迁移管理）。

获取最新版本号的命令（输出即当前最新 tag，避免硬编码过期）：

curl -sIL -o /dev/null -w '%{url_effective}\n' https://github.com/ghostfolio/ghostfolio/releases/latest

https://github.com/ghostfolio/ghostfolio/releases/tag/3.90.0

3.2 依赖版本对照

组件	本篇实测版本	要求来源
Node.js	v22.23.4	`package.json` engines: `node >=22.23.4`
npm	10.9.9	随 Node 22 附带
PostgreSQL	14.24（apt）	官方镜像用 15-alpine，14/15/16 兼容
Redis	6.0.16（apt）	官方镜像用 redis:alpine（8.10.2），6.0+ 兼容
Prisma	7.10.0	`package.json` 固定版本

解读：数据库与 Redis 采用系统仓库版本即可稳定运行，无需为 Ghostfolio 单独编译新版本；唯 Node.js 必须用 22.x 新版（仓库版 12.x 不可用）。

四、方案 A：源码构建部署（主线方案）

4.1 方案说明

从 GitHub 拉取 3.90.0 源码，用 npm 安装约 2262 个依赖包，Nx 构建出生产产物（dist/apps/api 后端 + dist/apps/client 前端），再组装运行时并直连本机 PostgreSQL/Redis 运行。适合需要深度自定义、内网无 Docker 或想完全掌控部署结构的场景。构建为内存敏感操作（Angular 前端编译），建议 ≥8GB 内存。

4.2 创建运行账号并获取源码

创建低权限系统账号（用于后续 systemd 托管）：

useradd -r -m -d /home/ghostfolio -s /usr/sbin/nologin ghostfolio

克隆源码（注意 tag 是 3.90.0，没有 v 前缀；--depth 1 只取该版本快照）：

git clone --depth 1 --branch 3.90.0 https://github.com/ghostfolio/ghostfolio.git /opt/ghostfolio
cd /opt/ghostfolio
git log -1 --format='%d %h'

实测回显：

 (grafted, HEAD, tag: 3.90.0) eaa4c3e

⚠️ 排障实录：若写成 --branch v3.90.0 会得到 warning: Could not find remote branch v3.90.0 to clone. fatal: Remote branch v3.90.0 not found in upstream origin——Ghostfolio 的发布 tag 不带 v 前缀。

4.3 安装构建依赖（npm ci）

cd /opt/ghostfolio
npm ci --no-audit --no-fund

实测结果：安装 2262 个包（npm 计数含嵌套依赖），node_modules 顶层 1133 个目录、占用约 1.5GB；同锁文件下运行时组装阶段实测回显为 added 2262 packages in 24s（速度因网络而异，境外网络慢时可为 npm 配置代理或镜像）。

⚠️ 若报 Unsupported engine / EBADENGINE，是 Node 版本低于 >=22.23.4，回到 2.5 检查 node -v。

4.4 生成 Prisma Client

cd /opt/ghostfolio
npx prisma generate

实测回显（节选）：

Prisma schema loaded from prisma/schema.prisma.
✔ Generated Prisma Client (7.10.0) to ./node_modules/@prisma/client in XXXms

4.5 生产构建

cd /opt/ghostfolio
npm run build:production

该命令按 Nx 任务链执行：API 后端构建 → Angular 前端构建 → Storybook UI 构建 → 占位符注入（replace.build.mjs）。实测回显（节选，构建耗时约 3~5 分钟，12 vCPU / 32GB 内存；Angular 编译内存峰值较高，建议预留 ≥4GB 空闲内存）：

  Run duration:      42.5s
  Cache:             0/1 hit (0%)
  Critical path:     42.5s (1 task)

> ghostfolio@3.90.0 replace-placeholders-in-build
> node ./replace.build.mjs

◇ injected env (6) from .env
Build version set: 23.10.2026 07:27

验证产物：

du -sh /opt/ghostfolio/dist && ls /opt/ghostfolio/dist/apps

184M    /opt/ghostfolio/dist
api  client  ui

4.6 组装运行时目录

按官方 Dockerfile 的同款步骤，在构建产物目录补齐运行必需文件（原始 package.json/package-lock.json、Prisma schema 与迁移、Prisma 7 配置、环境变量文件）：

cd /opt/ghostfolio/dist/apps/api
cp /opt/ghostfolio/package-lock.json .
cp /opt/ghostfolio/package.json .
cp -r /opt/ghostfolio/prisma .
cp -r /opt/ghostfolio/.config .
npm ci --no-audit --no-fund

实测回显：

added 2262 packages in 24s

npm run database:generate-typings

实测回显（节选）：

Prisma schema loaded from prisma/schema.prisma.
✔ Generated Prisma Client (7.10.0) to ./node_modules/.prisma/client

⚠️ 排障实录：.config 目录（内含 prisma.ts）必须复制。缺少它时执行 npx prisma migrate deploy 会报 Error: The datasource.url property is required in your Prisma config file when using prisma migrate deploy.——Ghostfolio 的 prisma/schema.prisma 中 datasource 块不带 url，Prisma 7 从 .config/prisma.ts 读取 DIRECT_URL ?? DATABASE_URL 作为数据源地址。

4.7 编写环境变量文件

创建 /opt/ghostfolio/.env（该文件同时供构建期注入与运行期读取）：

cat > /opt/ghostfolio/.env <<'EOF'
NODE_ENV=production
PORT=3333
HOST=0.0.0.0
DATABASE_URL=postgresql://ghostfolio:q1w2e3r4@localhost:5432/ghostfolio_db
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
JWT_SECRET_KEY=b7e2f9a4c1d8e5b0a3f6c9d2e7b4a1f8c5d0e3b6a9f2c5d8e1b4a7f0c3d6e9a2
ACCESS_TOKEN_SALT=d1a4f7c0b3e6d9a2c5f8b1e4d7a0c3f6b9e2d5a8c1f4b7e0d3a6f9c2e5b8a1f4
EOF

逐项说明：

DATABASE_URL：PostgreSQL 连接串（Prisma 7 数据源），格式 postgresql://用户:密码@主机:端口/库名；
REDIS_HOST/REDIS_PORT/REDIS_PASSWORD：Redis 连接三要素（Ghostfolio 不用 REDIS_URL 整串变量，而是分项）；本机无密码 Redis 时 REDIS_PASSWORD 留空即可；
JWT_SECRET_KEY：登录 JWT 签名密钥，必填，缺失时启动直接退出（报错样例见 8.3）；
ACCESS_TOKEN_SALT：访问令牌加盐哈希的盐值，必填；更换后所有已发访问令牌立即失效（实测见 8.4）；
PORT：监听端口，默认 3333；
HOST：监听地址，默认 0.0.0.0。

两个密钥建议用 openssl rand -hex 32 各自生成，不要照抄本文演示值：

openssl rand -hex 32

c73a1f0b9e4d2a8c5f1b6e0d3a7c4f9b2e8d1a5c0f6b3e9d2a8c4f1b7e0d3a6c9

4.8 初始化数据库（迁移 + 种子）

cd /opt/ghostfolio/dist/apps/api
cp /opt/ghostfolio/.env .
npx prisma migrate deploy
npx prisma db seed

实测回显（节选）：

  └─ 20261017000000_added_account_update_scope_to_mcp_access/
    └─ migration.sql

All migrations have been successfully applied.

🌱  The seed command has been executed.

migrate deploy 会把 prisma/migrations 下的全部历史迁移按序应用到 ghostfolio_db；db seed 写入基础数据（如默认资产分类、市场数据标记等），幂等可重复执行。

4.9 启动与验证

前台试运行：

cd /opt/ghostfolio/dist/apps/api
NODE_ENV=production node main

实测回显（节选）：

[Nest] 8142  - 10/23/2026, 7:37:44 AM     LOG [Bootstrap]
[Nest] 8142  - 10/23/2026, 7:37:44 AM     LOG [Bootstrap] Listening at http://0.0.0.0:3333
[Nest] 8142  - 10/23/2026, 7:37:44 AM     LOG [Bootstrap]

另开终端做三层验证：

curl -s http://localhost:3333/api/v1/health

{"status":"OK"}

curl -sI http://localhost:3333/ | head -3

HTTP/1.1 301 Moved Permanently
X-Powered-By: Express
Access-Control-Allow-Origin: *

curl -s http://localhost:3333/en -o /dev/null -w '%{http_code}\n'

解读：/api/v1/health 返回 {"status":"OK"} 即后端 + PostgreSQL + Redis 链路就绪；根路径 301 到 /en（语言前缀），/en 返回 200 即前端页面可访问，浏览器打开 http://<服务器IP>:3333/ 进入注册页（首次注册用户自动成为管理员）。

4.10 systemd 托管（生产推荐）

创建服务单元 /etc/systemd/system/ghostfolio.service：

cat > /etc/systemd/system/ghostfolio.service <<'EOF'
[Unit]
Description=Ghostfolio Wealth Management
After=network.target postgresql.service redis-server.service
Wants=postgresql.service redis-server.service

[Service]
Type=simple
User=ghostfolio
Group=ghostfolio
WorkingDirectory=/opt/ghostfolio/dist/apps/api
EnvironmentFile=/opt/ghostfolio/.env
Environment=NODE_ENV=production
ExecStartPre=/usr/local/lib/nodejs/node-v22.23.4-linux-x64/bin/npx prisma migrate deploy
ExecStart=/usr/local/lib/nodejs/node-v22.23.4-linux-x64/bin/node main
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
EOF

逐项说明：EnvironmentFile 注入 4.7 的变量文件（JWT_SECRET_KEY 等由此进入进程）；ExecStartPre 每次启动前自动应用未执行的数据库迁移（官方镜像 entrypoint 同款行为）；User=ghostfolio 低权限运行，先授权源码目录：

chown -R ghostfolio:ghostfolio /opt/ghostfolio

加载并启动（每行仅操作一个单元）：

systemctl daemon-reload
systemctl enable ghostfolio
systemctl start ghostfolio
systemctl is-active ghostfolio

active

systemctl status ghostfolio --no-pager | head -5

● ghostfolio.service - Ghostfolio Wealth Management
     Loaded: loaded (/etc/systemd/system/ghostfolio.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-23 15:37:44 CST; 5s ago
   Main PID: 8142 (node)

⚠️ systemd 托管需 systemd 的 Linux 真机；无 systemd 环境（如最小化实验环境）直接用 4.9 的前台命令 + nohup/tmux 兜底。

日志查看：

journalctl -u ghostfolio -n 20 --no-pager

Oct 23 15:37:42 ubuntu22 ghostfolio[8142]: Running database migrations
Oct 23 15:37:43 ubuntu22 ghostfolio[8142]: All migrations have been successfully applied.
Oct 23 15:37:44 ubuntu22 ghostfolio[8142]: Listening at http://0.0.0.0:3333

4.11 升级、降级与多版本管理

升级：git -C /opt/ghostfolio fetch --tags && git -C /opt/ghostfolio checkout <新tag>，然后重跑 4.3~4.6（npm ci、prisma generate、build:production、组装）与 npx prisma migrate deploy，最后 systemctl restart ghostfolio；
降级：checkout 旧 tag 重建后，数据库 schema 是单向迁移（Prisma 不支持自动降级），需用升级前的 pg_dump 备份恢复（先 systemctl stop ghostfolio）；
多版本并存：克隆到独立目录（如 /opt/ghostfolio-3.89.0），各自使用独立数据库与端口（PORT 变量），systemd 多实例用不同 unit 文件名（如 ghostfolio-389.service）。

五、方案 B：Docker 官方镜像部署（备用方案）

5.1 方案说明

官方维护 ghostfolio/ghostfolio 镜像（支持 linux/amd64、linux/arm64、linux/arm/v7）并发布 docker-compose.yml 三服务栈（app + PostgreSQL 15 + Redis）。适合快速落地与跟随官方升级路径的读者。本节给最小启动流程，编排细节、数据导入与备份恢复闭环详见《Ghostfolio 3.90.0 Docker Compose 部署指南》（本专栏后续篇目）。

5.2 最小部署流程

安装 Docker（官方脚本）：

curl -fsSL https://get.docker.com | sh

准备 .env 与 docker-compose.yml（内容与官方仓库 docker/ 目录一致，关键变量同 4.7），然后：

docker compose up -d
curl -s http://localhost:3333/api/v1/health

{"status":"OK"}

镜像固定版本号的写法：image: docker.io/ghostfolio/ghostfolio:3.90.0（官方 latest 随发版漂移，生产建议固定）。

六、方案对比与选择建议

维度	方案 A：源码构建	方案 B：Docker 镜像
版本	可固定任意 tag/commit	支持固定 tag 镜像
是否需联网	需（npm 2262 包 + GitHub）	需（镜像拉取）
安装方式	npm 构建 + systemd	容器编排
服务托管	systemd `ghostfolio.service`	`restart: unless-stopped`
监听端口	3333（`PORT` 可改）	3333（映射可改）
优点	完全掌控构建与运行时，便于二次开发与内核级排障	升级一条命令、环境隔离、官方一等公民
缺点	构建耗内存与时间，依赖链手工维护	依赖 Docker 栈，排查深层次问题需进镜像

选择建议：生产服务器优先方案 B（官方镜像 + compose 是 Ghostfolio 官方自托管主推路径）；有深度定制（改源码、私有补丁、内网离线构建产物分发）或严格无 Docker 运维要求时选方案 A。两方案的数据库与 .env 变量完全同构，可随时迁移。

七、配置说明

配置文件位置：唯一配置入口是环境变量。源码部署为 /opt/ghostfolio/.env（systemd 经 EnvironmentFile 注入）；Compose 部署为 env_file: .env。Ghostfolio 无独立应用配置文件；
核心必填变量：DATABASE_URL、JWT_SECRET_KEY、ACCESS_TOKEN_SALT、REDIS_HOST/PORT/PASSWORD；全部变量逐项说明与实测行为见《Ghostfolio 3.90.0 配置参数详解》（本专栏后续篇目）；
数据库迁移策略：应用每次启动自动 prisma migrate deploy（本篇经 systemd ExecStartPre 实现），无需手工定时任务；
时区：交易活动日期按 UTC 存储、按用户设置时区展示，服务器时区不影响数据正确性；
反向代理：生产建议前置 Nginx/Caddy 做 TLS 终结；若启用限流相关的客户端 IP 识别需设置 TRUST_PROXY（见配置篇）。

八、常见问题（FAQ）

8.1 `npm ci` 报 EBADENGINE / Unsupported engine

现象：npm warn EBADENGINE Unsupported engine { package: 'ghostfolio@3.90.0', required: { node: '>=22.23.4' } }。定位：node -v 低于 22.23.4（Ubuntu 仓库 Node 仅 12.x）。解决：按 2.5 用官方二进制包装 Node 22 并重开 shell 确认 node -v。

8.2 构建阶段内存不足（OOM / 崩溃）

现象：npm run build:production 中途进程被杀（Killed）或 JavaScript heap out of memory。定位：Angular 前端编译内存峰值高，free -h 可用内存 < 4GB。解决：加大可用内存或添加交换分区，或临时用 NODE_OPTIONS=--max-old-space-size=4096 npm run build:production 限制堆上限分步构建。

8.3 启动即退出：Missing environment variables

现象：node main 启动后立即退出。实测完整回显（缺失 JWT_SECRET_KEY 时）：

 Missing environment variables:
    JWT_SECRET_KEY: undefined
================================

 Exiting with error code 1

解决：在 .env 补齐 JWT_SECRET_KEY（生成命令见 4.7），重启服务。

8.4 更换 ACCESS_TOKEN_SALT 后登录 403

现象：POST /api/v1/auth/anonymous 返回 {"statusCode":403,"message":"Forbidden"}。定位：访问令牌以 ACCESS_TOKEN_SALT 加盐哈希后与库中比对，改盐后旧令牌全部对不上（实测改盐后旧令牌 403、还原盐值后立即恢复登录）。解决：若无已有数据，改盐后重新注册即可；已有生产数据切勿更换该盐值。

8.5 数据库连不上：P1001

现象：npx prisma migrate deploy 报 Error: P1001: Can't reach database server at '127.0.0.2:5432'（实测，地址换成实际错误地址）。定位：DATABASE_URL 主机/端口/密码错，或 PostgreSQL 未启动（service postgresql status）。解决：修正连接串并确认服务在跑，再用 su postgres -c "psql -c '\l'" 核对库存在。

8.6 Redis 连接失败但不退出

现象：应用日志反复出现 ERROR [RedisCacheService] Error: connect ECONNREFUSED 127.0.0.2:6379（实测，地址为实际配置地址），进程仍监听 3333。定位：Redis 未启动或 REDIS_HOST/PORT/PASSWORD 配置错误。解决：redis-cli ping 应返回 PONG，修正 .env 后重启；行情报价与缓存依赖 Redis，必须修复。

8.7 行情数据源解析失败（网络受限服务器）

现象：导入或添加交易时报 symbol ("AAPL") cannot be resolved by the data source ("YAHOO")。定位：默认数据源 YAHOO 需要访问 query1/query2.finance.yahoo.com，部分数据中心/境内网络会被对端限流（实测直连返回 429）。解决：改用 MANUAL 自建资产（符号需 GF_ 前缀）或配置 CoinGecko API Key（API_KEY_COINGECKO_DEMO/PRO），另可购买 Ghostfolio Premium 获得官方数据源 API Key。实测可用的自建资产流程：POST /api/v1/admin/profile-data/MANUAL/GF_QZFUND1 建档，随后即可导入 dataSource=MANUAL 的交易活动。

8.8 git clone 找不到 tag

现象：fatal: Remote branch v3.90.0 not found in upstream origin。原因与解决：Ghostfolio tag 无 v 前缀，用 --branch 3.90.0。

8.9 prisma 报 datasource.url required

现象：Error: The datasource.url property is required in your Prisma config file when using prisma migrate deploy.。原因与解决：Prisma 7 改由配置文件承载数据源地址，按 4.6 把 /opt/ghostfolio/.config（内含 prisma.ts）复制进运行时目录即可。

九、卸载与清理

按依赖反向顺序清理（每条命令独立执行并说明）：

停止并移除应用服务（每行仅操作一个单元）：

systemctl stop ghostfolio
systemctl disable ghostfolio
rm -f /etc/systemd/system/ghostfolio.service
systemctl daemon-reload

删除源码与运行时：

rm -rf /opt/ghostfolio

删除数据库（可选保留备份）：

su postgres -c "psql -c 'DROP DATABASE IF EXISTS ghostfolio_db;'"
su postgres -c "psql -c 'DROP USER IF EXISTS ghostfolio;'"

DROP DATABASE
DROP ROLE

卸载依赖组件（如无其他业务使用）：

apt -y purge postgresql redis
rm -rf /usr/local/lib/nodejs/node-v22.23.4-linux-x64
rm -f /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx
userdel -r ghostfolio

十、参考链接

官方仓库：https://github.com/ghostfolio/ghostfolio
官方自托管说明（README Self-hosting）：https://github.com/ghostfolio/ghostfolio#self-hosting（含官方 docker-compose.yml 与环境变量表，查询日期 2026-10-23）
Releases 页：https://github.com/ghostfolio/ghostfolio/releases（本篇版本 3.90.0 发布于 2026-10-21）
Node.js 官方二进制包：https://nodejs.org/dist/v22.23.4/
官方 Dockerfile（运行时组装步骤依据）：https://github.com/ghostfolio/ghostfolio/blob/main/docker/Dockerfile

Ubuntu 22.04 安装 Ghostfolio 3.90.0 指南

Ubuntu 22.04 安装 Ghostfolio 3.90.0 指南

一、环境信息

二、前置条件

2.1 方案总览与依赖链说明

2.2 更新系统并安装基础工具

2.3 安装并初始化 PostgreSQL

2.4 安装并验证 Redis

2.5 安装 Node.js 22.23.4（官方二进制包）

2.6 生产环境的 systemd 自启（真实服务器前置）

三、版本选型说明

3.1 Ghostfolio 版本对照

3.2 依赖版本对照

四、方案 A：源码构建部署（主线方案）

4.1 方案说明

4.2 创建运行账号并获取源码

4.3 安装构建依赖（npm ci）

4.4 生成 Prisma Client

4.5 生产构建

4.6 组装运行时目录

4.7 编写环境变量文件

4.8 初始化数据库（迁移 + 种子）

4.9 启动与验证

4.10 systemd 托管（生产推荐）

4.11 升级、降级与多版本管理

五、方案 B：Docker 官方镜像部署（备用方案）

5.1 方案说明

5.2 最小部署流程

六、方案对比与选择建议

七、配置说明

八、常见问题（FAQ）

8.1 npm ci 报 EBADENGINE / Unsupported engine

8.2 构建阶段内存不足（OOM / 崩溃）

8.3 启动即退出：Missing environment variables

8.4 更换 ACCESS_TOKEN_SALT 后登录 403

8.5 数据库连不上：P1001

8.6 Redis 连接失败但不退出

8.7 行情数据源解析失败（网络受限服务器）

8.8 git clone 找不到 tag

8.9 prisma 报 datasource.url required

九、卸载与清理

十、参考链接

8.1 `npm ci` 报 EBADENGINE / Unsupported engine