在本地运行 Deployment 课程项目

使用这个页面在你的计算机上运行提取的 Dream Catcher 项目，用你自己的 OpenAI 密钥获得梦境解读。你的副本将梦境保存在两个数据库之一中：项目文件夹内的 SQLite 文件，或你连接的 PostgreSQL 数据库。大部分设置对两个版本都相同；PostgreSQL 版本需要额外的几行，下面有标记。

你首先需要的

安装受支持的 LTS 版本的 Node.js。推荐使用 Node 24，它包含 npm。

检查两个命令都能工作。你的版本号可能不同：

$ node --version
v24.18.0
$ npm --version
11.18.0

你还需要一个 OpenAI API 密钥，因为服务器会为每个解读请求 OpenAI。密钥保留在服务器上，保存在你计算机的一个文件中，永远不会到达浏览器。

然后找出你拥有的是哪个版本。在提取的 Dream Catcher 文件夹中打开终端（包含 package.json 和 server.js 的文件夹），列出其文件：

$ cd path-to-your-dream-catcher-folder
$ ls
README.md          package.json
config             public
dreams.db          routes
hint.md            server.js
package-lock.json  utils

如果列表中包含 dreams.db，你有 SQLite 版本：数据库就是该文件，没有其他需要设置的。如果没有 dreams.db，你有 PostgreSQL 版本，还需要一个 PostgreSQL 数据库和它的连接字符串，一个以 postgresql:// 或 postgres:// 开头的 URL。使用托管数据库最简单，比如你在课程部署中在 Render 上设置的那个。Render 的免费数据库在创建后 30 天过期，所以如果你的已经过期，创建一个新的。

忽略文件夹中的 README.md。它描述的是应用的旧版本，使用不同的 AI 提供商和端口。

Juno你首先需要的 检查 node --version 和 npm --version 都输出版本号，并准备好 OpenAI API 密钥。

然后在项目文件夹中运行 ls。如果你看到 dreams.db，你不需要其他任何东西；如果没有，你还需要一个 PostgreSQL 数据库 URL。

Juno你首先需要的 这里一个 Express 服务器完成所有工作：它向你的浏览器发送页面，读写数据库，并调用 OpenAI。两个版本只在 config/database.js 中有所不同，它在一个版本中打开 dreams.db，在另一个版本中连接到 DATABASE_URL。

Juno你首先需要的 浏览器只调用该服务器的 /api/dreams 路由，OpenAI 客户端在服务器内部创建，所以没有什么会将密钥复制到浏览器下载的代码中。package.json 与文件检查一致：一个版本中有 sqlite3，另一个版本中有 pg。

安装包

在同一个终端中，安装项目在其锁文件中列出的确切版本：

$ npm ci

npm 会输出它添加了多少个包。它还会打印关于已弃用包、漏洞和 allow-scripts 的警告。这些都不会阻止项目运行；保持原样。

Juno安装包 在包含 package.json 的文件夹中运行 npm ci，等待输出显示添加了多少个包的那行。

后面的警告是正常的。如果 npm 说找不到 package.json，你在错误的文件夹中。

Juno安装包npm ci 安装 package-lock.json 记录的确切内容，拒绝改变它，所以你得到课程使用的相同包。在 SQLite 版本中，它还会获取为你的计算机构建的 SQLite 驱动程序。

Juno安装包sqlite3 是一个原生模块，所以它的安装脚本为你的操作系统和处理器下载一个构建。这就是为什么从另一台计算机复制的 node_modules 无法加载，以及为什么 npm 在其 allow-scripts 警告中命名 sqlite3。

让 npm start 读取你的 .env 文件

服务器从 process.env 读取设置，但项目的启动命令不加载 .env 文件，所以服务器会在没有你的密钥的情况下启动并立即停止。打开 package.json 并更改：

"start": "node server.js"

为：

"start": "node --env-file=.env server.js"

Node 现在在服务器代码运行之前自己读取 .env 一次。如果文件缺失，Node 会停止并显示 node: .env: not found。

然后打开 .gitignore。它应该列出 .env，所以 Git 永远不会保存你的密钥，以及 node_modules。在 SQLite 版本中，第二行拼写错误为 mode_modules；更正它，使其读取：

node_modules
.env

保留已经存在的 logs 和 *.log 行。Git 手册在忽略文件和良好实践中解释了为什么这些条目很重要。

Juno让 npm start 读取你的 .env 文件 在 package.json 中，向 start 脚本添加 --env-file=.env。然后检查 .gitignore 列出 node_modules 和 .env，拼写完全一致。

Juno让 npm start 读取你的 .env 文件 在 Scrimba 和 Render 这样的宿主上，设置在服务器启动时已经在环境中。在你的计算机上它们存在于文件中，--env-file 是 Node 的内置加载方式，不需要额外的包。

Juno让 npm start 读取你的 .env 文件 如果一个变量已经在你的 shell 中设置，它会覆盖 .env 中的同名变量。如果你曾在这个终端中导出 OPENAI_API_KEY，那个旧值就是服务器获得的。

添加你的 .env 并启动

在 package.json 旁边创建一个名为 .env 的文件。SQLite 版本只需要密钥行；PostgreSQL 版本还需要 DATABASE_URL 行：

# 仅 PostgreSQL 版本
DATABASE_URL=postgresql://user:password@host:5432/database

OPENAI_API_KEY=your-openai-key-here

对于 PostgreSQL，将整个示例 URL 替换为你的宿主提供的用于从其网络外部连接的 URL（在 Render 上，数据库的 Connect 菜单中的外部 URL）。除非你添加 OPENAI_MODEL 或 PORT 行以选择其他选项，否则服务器使用 gpt-4o-mini 和端口 3001。

启动服务器：

$ npm start
Server running on http://localhost:3001

PostgreSQL 版本首先打印 Database initialized：它连接到数据库并在开始监听前创建其表，所以 Server running 只在数据库响应后出现一次。如果终端打印 Failed to initialize database: 相反，服务器已停止；下面的故障排除与其后的错误匹配。在 PostgreSQL 版本中，你还可以打开 http://localhost:3001/health；工作的连接会用包含 "status":"ok" 和 "db":"connected" 的 JSON 响应。

打开 http://localhost:3001。页面显示 Add a New Dream 并在 Your Dream Journal 下显示"No dreams yet"，因为两个数据库都是从空开始的。描述一个梦境并点击 Get Interpretation。当 OpenAI 写入时按钮读取 Interpreting...，然后你的梦境连同其解读出现在日志中。

如果解读失败，页面显示一个错误：SQLite 版本中的"Network error. Please check your connection and try again."（显示该消息表示每个失败），或 PostgreSQL 版本中的"AI service temporarily unavailable."。无论如何，看终端而不是你的连接。原因跟在 OpenAI API error: 后面，在长块详情上方；下面的故障排除匹配每一个。

用 Ctrl+C 停止服务器。Node 只在服务器启动时读取 .env，所以在任何对 .env 的更改后重新启动。PostgreSQL 版本仍然有课程的 /shutdown 测试路由，在打开时停止服务器；在部署前删除它。

Juno添加你的 .env 并启动 将你的密钥，以及对于 PostgreSQL 你的数据库 URL，放在 .env 中。运行 npm start，等待 Server running，并打开 http://localhost:3001。添加一个梦境并点击 Get Interpretation。

如果页面显示错误，读终端：原因打印在那里。

Juno添加你的 .env 并启动 看到页面证明 Express 在提供它，数据库已打开。解读是服务器首次调用 OpenAI 的时刻，所以日志中的新梦境是证明你的密钥有效的标志。

Juno添加你的 .env 并启动 SQLite 版本的 app.js 在服务器以错误响应时读取未定义的 data 变量，所以 ReferenceError 落入其网络错误 catch 中。PostgreSQL 连接池总是请求加密连接；你自己计算机上的 PostgreSQL 服务器通常关闭了加密，所以 pg 停止并显示 The server does not support SSL connections。

故障排除

启动时出现 OpenAIError: The OPENAI_API_KEY environment variable is missing or empty： 服务器在能够监听前停止；该消息出现在指向 openai/index.mjs 的几行后面。检查启动脚本包含 --env-file=.env，.env 在 package.json 旁边，并且名称完全是 OPENAI_API_KEY。

node: .env: not found： 启动脚本正确，但你启动的文件夹中没有 .env。在 package.json 旁边创建它。

401 Incorrect API key provided： 密钥到达了 OpenAI，但 OpenAI 没有接受它。从你的 OpenAI 账户再次复制它，保存 .env，并重新启动服务器。

429 You exceeded your current quota： 密钥有效，但账户没有信用可以花费。在你的 OpenAI 账户中 Billing 下添加信用，然后重试。

The model ... does not exist： OpenAI 计划在 2027 年 1 月 14 日关闭 gpt-4o-mini。在那之后，向 .env 添加 OPENAI_MODEL 行，其值为 OpenAI 的弃用页面命名的替代品，并重新启动。

Error: Could not locate the bindings file（SQLite 版本）： 你的计算机缺少 SQLite 驱动程序。删除 node_modules 并在此文件夹中再次运行 npm ci。不要从另一台计算机复制 node_modules。

Failed to initialize database: 伴随 ENOTFOUND： DATABASE_URL 中的主机名在你的网络上不存在。检查你是否替换了整个示例 URL，以及你是否复制了外部 URL，而不是仅在你的宿主网络内工作的内部 URL。

Failed to initialize database: 伴随 ECONNREFUSED： 该地址处没有任何应答。如果错误命名了你自己计算机上的端口 5432（::1 或 127.0.0.1），DATABASE_URL 在 .env 中缺失或指向未运行的 PostgreSQL。

Failed to initialize database: 伴随 password authentication failed： DATABASE_URL 中的用户名或密码错误。从你的数据库宿主再次复制 URL。

Failed to initialize database: 伴随 The server does not support SSL connections： 你在使用没有加密的 PostgreSQL 服务器，通常是你自己计算机上的。仅用于本地使用，向 DATABASE_URL 末尾添加 ?sslmode=disable，或改用托管数据库。

Juno故障排除 读终端，不是页面。找到第一行包含 Error 的行，并将其措辞与上面的粗体标题匹配。然后修复 .env 或命名的文件，并再次运行 npm start。

Juno故障排除 每个问题在它自己的时刻出现：缺少密钥或 .env 在启动时立即出现，数据库问题在 Server running 前，密钥、信用或模型问题只在你点击 Get Interpretation 时出现。

Juno故障排除 OpenAI 客户端在 server.js 导入其路由时构建，所以缺少密钥会在 server.js 的任何行运行前停止 Node。错误的密钥会通过该检查，仅在第一个请求时失败，显示 401。