Yohaku 项目完整 Wiki

·(已编辑)· / , ·

阅读·

喜欢

这篇文章上次修改于，可能部分内容已经不适用，如有疑问可询问作者。

关键洞察

AI · GEN

Yohaku 项目完整 Wiki

本文档基于当前仓库中的部署文件，以及上游前端 Yohaku / 兼容后端 MX Space Core 的公开代码结构整理而成。
所有示例都已做隐私脱敏：请把文中的占位符替换成你自己的值，不要直接把真实域名、用户名、Token、密钥写进 Git 仓库。

0. 官方链接与源项目入口

这一节用于补充本文档提到的上游项目主页、官方文档和技术栈入口。
如果你后续要二次开发、排查兼容性问题、升级依赖或比对官方说明，可以优先从这里进入。

0.1 核心源项目入口

Yohaku 公共项目主页：https://github.com/Innei/Yohaku
MX Space Core 后端项目主页：https://github.com/mx-space/core

说明：你当前部署流程中实际使用的前端源码仓库可能是私有仓库，例如工作流里配置的私有 repository。
为避免把你的私有地址或权限信息写进 Wiki，这里统一只放公开项目主页；实际部署时请把它替换成你自己有权限访问的源码地址。

0.2 关键技术栈官方文档

Next.js 文档：https://nextjs.org/docs
React 文档：https://react.dev/
pnpm 安装与使用：https://pnpm.io/installation
Turborepo 文档：https://turborepo.dev/repo/docs
Tailwind CSS 文档：https://tailwindcss.com/docs/installation
TypeScript 文档：https://www.typescriptlang.org/docs/
Docker 文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/
GitHub Actions 文档：https://docs.github.com/actions
OpenResty 官网：https://openresty.org/en/
OpenResty 仓库：https://github.com/openresty/openresty
Nginx 文档：https://nginx.org/en/docs/
Socket.IO 文档：https://socket.io/docs/v4/
MongoDB 文档：https://www.mongodb.com/docs/
Redis 文档：https://redis.io/docs/latest/
Better Auth 文档：https://better-auth.com/docs/introduction
TMDB 开发者文档：https://developer.themoviedb.org/v3/reference/intro/getting-started
Git LFS 官网：https://git-lfs.com/

0.3 建议阅读顺序

如果你是第一次接手这个项目，建议按这个顺序阅读：

先看本文第 2、3 节，理解前后端拓扑和职责
再看第 8、9 节，完成本地开发或服务器搭建
然后看第 11、12 节，理解镜像构建和 CI/CD
最后看第 16、21、22 节，完成反代、安全和排障

1. 这份仓库是什么

当前这个本地仓库不是完整业务源码仓库，而是一个部署仓库，主要包含：

前端镜像构建用的 Dockerfile.hub
GitHub Actions 工作流 .github/workflows/dockerhub.yml
服务器侧部署文件 deploy/docker-compose.yml
服务器侧环境变量模板 deploy/yohaku.env.example
OpenResty / Nginx 反向代理示例（当前仓库中的 deploy/*.conf）

也就是说：

前端业务源码来自上游 Yohaku 项目
后端服务不是这个仓库的一部分，前端通过 API_URL / NEXT_PUBLIC_API_URL 去连接兼容的 CMS API

如果你只看当前仓库，可以把它理解为：

在 CI 或本地构建前端镜像
推送镜像到 Docker Hub
在服务器只做 docker pull + docker compose up -d
让前端通过环境变量去连接现有后端

2. 项目总体架构

2.1 逻辑拓扑

CodeBlock Loading...

2.2 端口约定

建议统一约定如下：

前端容器：2323
后端容器：2333
前端公网入口：https://<YOUR_FRONTEND_DOMAIN>
后端公网入口：https://<YOUR_API_DOMAIN>

2.3 当前方案的关键思想

浏览器可见的地址走公网域名
前端 SSR 访问后端优先走内网地址 API_URL
密钥类变量只放服务器，不放镜像
前端更新只需要重建镜像，不需要在服务器源码编译

3. 前后端职责划分

3.1 前端（Yohaku）

前端是一个 pnpm + turbo 的 monorepo，主应用是：

CodeBlock Loading...

核心技术栈：

Node.js >= 20
pnpm 10.27.0
Turbo Repo
Next.js 16
React 19
Tailwind CSS 4
output: standalone 方式打包

前端相关官方入口：

项目主页：https://github.com/Innei/Yohaku
Next.js 文档：https://nextjs.org/docs
React 文档：https://react.dev/
pnpm 文档：https://pnpm.io/installation
Turborepo 文档：https://turborepo.dev/repo/docs
Tailwind CSS 文档：https://tailwindcss.com/docs/installation
TypeScript 文档：https://www.typescriptlang.org/docs/

前端主要负责：

页面渲染（SSR / RSC / 客户端交互）
多语言路由
评论、文章、页面、说说、时间线等页面展示
Webhook 触发的页面再验证
代理 GitHub / TMDB 等第三方接口
通过 WebSocket 接收实时事件

3.2 后端（MX Space Core / 兼容实现）

从前端依赖和官方后端公开信息看，兼容后端一般具备：

Node.js >= 22
NestJS
MongoDB 7
Redis 7
Socket.IO
Better Auth / OAuth / Passkey
REST API（/api/v2）
WebSocket 网关（/web）

后端与基础设施官方入口：

后端项目主页：https://github.com/mx-space/core
MongoDB 文档：https://www.mongodb.com/docs/
Redis 文档：https://redis.io/docs/latest/
Socket.IO 文档：https://socket.io/docs/v4/
Better Auth 文档：https://better-auth.com/docs/introduction

后端主要负责：

内容管理：文章、页面、笔记、分类、评论、项目等
聚合接口：站点信息、聚合首页数据
认证接口：/auth
实时推送：Socket.IO
回调前端 /api/webhook 触发缓存失效与再验证

4. 目录说明

4.1 当前部署仓库

CodeBlock Loading...

4.2 前端上游源码仓库（逻辑结构）

CodeBlock Loading...

4.3 后端兼容仓库（逻辑结构）

CodeBlock Loading...

5. 你需要先准备什么

5.1 本地开发机

建议安装：

Node.js 20.x（前端）
Node.js 22.x（如果你也要跑后端源码）
corepack
pnpm
git
git-lfs
docker
docker compose

macOS 示例：

CodeBlock Loading...

Ubuntu / Debian 示例：

CodeBlock Loading...

5.2 服务器

建议准备一台 Linux 服务器，并安装：

Docker
Docker Compose Plugin
OpenResty 或 Nginx
域名与 HTTPS 证书

建议目录：

CodeBlock Loading...

6. 域名、路径、镜像命名建议

为避免文档里出现真实信息，全文统一使用下列占位符：

占位符	含义	示例
`<YOUR_FRONTEND_DOMAIN>`	前端域名	`blog.example.com`
`<YOUR_API_DOMAIN>`	后端 API / 网关域名	`api.example.com`
`<YOUR_DOCKERHUB_USERNAME>`	Docker Hub 用户名	`yourname`
`<YOUR_SOURCE_REPO>`	前端源码仓库	`owner/Yohaku`
`<BACKEND_INTERNAL_HOST>`	前端容器访问后端的内网主机名	`mx-core`
`<YOUR_GITHUB_TOKEN>`	GitHub Token	`ghp_xxx`
`<YOUR_TMDB_API_KEY>`	TMDB Token / API Key	`xxx`

推荐映射：

前端公网域名：https://<YOUR_FRONTEND_DOMAIN>
后端公网域名：https://<YOUR_API_DOMAIN>
前端镜像：<YOUR_DOCKERHUB_USERNAME>/yohaku-web:latest
服务器前端目录：/opt/yohaku
服务器前端环境变量：/opt/yohaku-env/yohaku.env
服务器后端目录：/opt/mx-space

7. 环境变量总表

7.1 前端公开构建变量

这些变量最终会暴露到浏览器，可以写进构建参数：

变量名	是否必须	说明	示例
`NEXT_PUBLIC_API_URL`	是	浏览器请求 API 的公开地址	`https://<YOUR_API_DOMAIN>/api/v2`
`NEXT_PUBLIC_CLIENT_API_URL`	建议	浏览器侧单独指定 API 地址	`https://<YOUR_API_DOMAIN>/api/v2`
`NEXT_PUBLIC_GATEWAY_URL`	是	WebSocket / 网关地址，不带 `/web`	`https://<YOUR_API_DOMAIN>`

7.2 前端运行时变量

这些变量不要写死进镜像：

变量名	是否必须	说明	示例
`API_URL`	强烈建议	前端 SSR 访问后端的内网地址	`http://mx-core:2333/api/v2`
`WEBHOOK_SECRET`	建议	前端 `/api/webhook` 验签密钥	随机字符串
`TMDB_API_KEY`	可选	前端 TMDB 代理接口使用	`xxx`
`GH_TOKEN`	可选	前端 GitHub 代理接口使用	`ghp_xxx`
`NODE_ENV`	是	环境模式	`production`
`HOSTNAME`	是	监听地址	`0.0.0.0`
`PORT`	是	前端监听端口	`2323`

7.3 后端核心变量

后端常见最小集：

变量名	是否必须	说明	示例
`JWT_SECRET`	是	JWT 签名密钥	随机字符串
`ALLOWED_ORIGINS`	是	允许跨域来源	`<YOUR_FRONTEND_DOMAIN>,www.<YOUR_FRONTEND_DOMAIN>`
`ENCRYPT_KEY`	建议	字段加密密钥，64 位十六进制	`openssl rand -hex 32`
`ENCRYPT_ENABLE`	建议	是否启用加密	`false`
`DB_CONNECTION_STRING` / `MONGO_CONNECTION`	是	MongoDB 连接串	`mongodb://mongo:27017/mx-space`
`REDIS_HOST`	是	Redis 主机	`redis`
`REDIS_PORT`	是	Redis 端口	`6379`
`PORT`	是	后端端口	`2333`
`TZ`	建议	时区	`Asia/Shanghai`

7.4 建议的密钥生成命令

CodeBlock Loading...

8. 前端本地开发搭建

如果你只是做部署，不一定要本地跑源码；但如果你要改主题、页面、文案、交互，就建议按这一节完整搭建。

8.1 拉取前端源码

CodeBlock Loading...

如果源码仓库是私有的：

CodeBlock Loading...

8.2 启用 pnpm

CodeBlock Loading...

8.3 安装依赖

CodeBlock Loading...

8.4 配置前端本地环境变量

可以在 apps/web/.env.local 写入：

CodeBlock Loading...

8.5 启动前端

在仓库根目录运行：

CodeBlock Loading...

或者只启动前端应用：

CodeBlock Loading...

默认访问：

CodeBlock Loading...

8.6 本地前端构建

CodeBlock Loading...

如果要验证 standalone 产物，通常会在构建后运行：

CodeBlock Loading...

实际生产镜像里运行的也是这个入口。

8.7 前端开发阶段可参考的官方链接

Next.js 路由、SSR、RSC、部署说明：https://nextjs.org/docs
React 新文档与 Hooks 说明：https://react.dev/
pnpm Workspace / 安装说明：https://pnpm.io/installation
Turborepo Monorepo 任务说明：https://turborepo.dev/repo/docs
Tailwind CSS 安装与配置：https://tailwindcss.com/docs/installation
TypeScript Handbook：https://www.typescriptlang.org/docs/

9. 后端本地 / 服务器搭建

这一节给两种方式：
方式 A：跑兼容后端源码
方式 B：直接用官方镜像起服务

9.1 方式 A：从源码启动后端

CodeBlock Loading...

后端默认端口：

CodeBlock Loading...

健康检查：

CodeBlock Loading...

如果正常，通常应返回：

CodeBlock Loading...

9.2 方式 B：用 Docker 直接部署后端

在 /opt/mx-space 下创建 .env：

CodeBlock Loading...

然后创建 /opt/mx-space/docker-compose.yml：

CodeBlock Loading...

启动：

CodeBlock Loading...

9.3 后端搭建阶段可参考的官方链接

MX Space Core 项目页：https://github.com/mx-space/core
MongoDB 官方文档：https://www.mongodb.com/docs/
Redis 官方文档：https://redis.io/docs/latest/
Socket.IO 文档：https://socket.io/docs/v4/
Better Auth 文档：https://better-auth.com/docs/introduction

10. 前端对后端的接口约定

这部分很重要，因为前端能不能跑起来，核心就在这里。

10.1 浏览器请求 API

浏览器端主要看：

CodeBlock Loading...

10.2 前端 SSR 请求 API

服务端渲染时，前端优先读取：

CodeBlock Loading...

也就是说：

浏览器访问：走公网域名
容器内部访问：走 Docker 内网主机名

这是最推荐的生产拓扑。

10.3 WebSocket 地址

前端会把：

CodeBlock Loading...

拼成：

CodeBlock Loading...

并通过 Socket.IO WebSocket 连接。

所以你的后端反向代理必须允许：

Upgrade
Connection
长连接超时

10.4 Auth 地址

前端认证客户端会把：

CodeBlock Loading...

作为认证基地址，所以后端需要兼容：

CodeBlock Loading...

10.5 Webhook 地址

后端内容变更后，应回调前端：

CodeBlock Loading...

并使用与前端一致的：

CodeBlock Loading...

完成签名验证。

11. 当前仓库的前端镜像构建方式

当前仓库采用：

GitHub Actions 拉取源码
用 Dockerfile.hub 构建
推送到 Docker Hub

11.1 `Dockerfile.hub` 的作用

它做了几件事：

安装 Node / pnpm / sharp
安装依赖
执行 pnpm --filter @shiro/web build:ci
将 Next.js standalone 产物复制到最终镜像
安装中文和英文字体
暴露 2323
运行 node apps/web/server.js

11.2 建议保留的 `Dockerfile.hub`

下面这份是可直接使用的隐私安全模板：

CodeBlock Loading...

11.3 镜像构建相关官方文档

Docker 官方文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/
Next.js 部署与构建文档：https://nextjs.org/docs

12. GitHub Actions 自动构建镜像

12.1 需要的 GitHub Secrets

在你的部署仓库中配置：

GH_PAT
- 用于读取前端源码仓库
DOCKERHUB_USERNAME
- Docker Hub 用户名
DOCKERHUB_TOKEN
- Docker Hub Access Token

12.2 推荐的工作流文件

保存为 .github/workflows/dockerhub.yml：

CodeBlock Loading...

12.3 首次触发

CodeBlock Loading...

然后在 GitHub 仓库中：

CodeBlock Loading...

12.4 GitHub Actions 相关官方文档

GitHub Actions 总文档：https://docs.github.com/actions
Docker 官方文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/

13. 前端生产环境变量文件

将以下内容保存为服务器上的：

CodeBlock Loading...

推荐模板如下：

CodeBlock Loading...

13.1 如果后端不在同一个 Docker 网络

如果后端不在同一个 compose 网络，而是在宿主机上跑，可以改成：

CodeBlock Loading...

Linux 若 host.docker.internal 不通，可尝试：

CodeBlock Loading...

但最佳实践仍然是前后端放在同一个 Docker 网络，直接用服务名互通。

14. 前端服务器部署（只部署前端）

如果你的后端已经跑好了，那么前端可以单独部署。

14.1 `/opt/yohaku/docker-compose.yml`

CodeBlock Loading...

14.2 启动命令

CodeBlock Loading...

15. 一体化部署（前后端同机同网）

如果你希望前后端一起放在一台服务器上，推荐直接用下面这个组合版 docker-compose.yml。

保存为：

CodeBlock Loading...

15.1 组合部署时前端 env 要这样写

CodeBlock Loading...

15.2 启动组合部署

CodeBlock Loading...

16. OpenResty / Nginx 反向代理

生产环境至少需要两套反代：
前端域名 -> 127.0.0.1:2323
后端域名 -> 127.0.0.1:2333

16.1 前端站点配置

保存为：

CodeBlock Loading...

16.2 后端站点配置（含 WebSocket）

保存为：

CodeBlock Loading...

16.3 HTTPS

建议通过：

1Panel
Certbot
acme.sh
云厂商证书托管

为这两个域名都签发 HTTPS。

如果使用 1Panel，原则上就是：

站点 A：<YOUR_FRONTEND_DOMAIN> -> 127.0.0.1:2323
站点 B：<YOUR_API_DOMAIN> -> 127.0.0.1:2333

并开启 WebSocket 支持。

16.4 反向代理与网关参考链接

OpenResty 官网：https://openresty.org/en/
OpenResty 仓库：https://github.com/openresty/openresty
Nginx 官方文档：https://nginx.org/en/docs/
Socket.IO 文档（排查 WebSocket / Upgrade 问题时很有用）：https://socket.io/docs/v4/

17. 本地手工构建并推送前端镜像

如果你暂时不想走 GitHub Actions，可以本地推镜像。

在前端源码根目录执行：

CodeBlock Loading...

18. 服务器上线顺序

推荐按这个顺序操作：

18.1 先起后端

CodeBlock Loading...

18.2 再起前端

CodeBlock Loading...

18.3 最后接入反向代理

CodeBlock Loading...

19. 上线后检查清单

19.1 检查前端容器

CodeBlock Loading...

19.2 检查后端容器

CodeBlock Loading...

19.3 检查前端健康接口

CodeBlock Loading...

应返回类似：

CodeBlock Loading...

19.4 检查后端健康接口

CodeBlock Loading...

19.5 检查前端容器内是否能访问后端

如果是组合部署：

CodeBlock Loading...

如果是宿主机互通：

CodeBlock Loading...

19.6 浏览器检查

浏览器打开：

CodeBlock Loading...

重点看：

首页是否能打开
文章 / 页面 / 说说是否能加载
控制台是否存在 CORS 报错
WebSocket 是否连接成功
登录 / 评论 / 搜索是否正常

20. Webhook 配置建议

前端存在：

CodeBlock Loading...

它会处理内容更新事件，并触发页面再验证。

20.1 需要保证

后端和前端共享同一个 WEBHOOK_SECRET
后端把内容更新事件发送到：

CodeBlock Loading...

20.2 健康检查类型

前端 webhook 路由支持 health_check 类型事件，并会返回：

CodeBlock Loading...

21. 常见故障排查

21.1 首页能开，但内容为空

通常是：

API_URL 错了
后端没起来
容器内访问不到后端

排查：

CodeBlock Loading...

21.2 浏览器请求报跨域

通常是后端：

CodeBlock Loading...

没包含前端域名。

建议设置为：

CodeBlock Loading...

21.3 WebSocket 连不上

通常是：

NEXT_PUBLIC_GATEWAY_URL 错了
后端反代没开 WebSocket Upgrade
后端域名证书问题

检查：

浏览器 Network -> WS
Nginx Upgrade / Connection 头
后端 /web 是否由反代正确转发

21.4 `host.docker.internal` 不通

解决顺序：

优先把前后端放在一个 compose 网络，用服务名访问
如果必须跨宿主机，Linux 再尝试 172.17.0.1
最后才考虑额外网桥配置

21.5 构建时报 `git-lfs` 相关错误

安装并初始化：

CodeBlock Loading...

GitHub Actions 中确保：

CodeBlock Loading...

并执行：

CodeBlock Loading...

21.6 `pnpm install --frozen-lockfile` 失败

通常是 pnpm 版本不匹配。

修复：

CodeBlock Loading...

21.7 排障时常用官方入口

pnpm 文档：https://pnpm.io/installation
Docker 文档：https://docs.docker.com/
GitHub Actions 文档：https://docs.github.com/actions
Nginx 文档：https://nginx.org/en/docs/
OpenResty 官网：https://openresty.org/en/
Git LFS 官网：https://git-lfs.com/

21.8 云函数 / Serverless 配置反复出错时，优先检查这些点

这一节是根据本项目代码结构、前后端运行方式，以及 Next.js / Vercel 类平台的运行特征整理的。
如果你之前在“云函数配置”这里反复出错，大概率就是下面这些配置项没有对齐。

21.8.1 把前端能上云函数，误以为后端也能完整上云函数

这个项目的前端是 Next.js，理论上可以部署到支持 Next.js 的云函数 / Serverless 平台。
但后端兼容实现 MX Space Core 依赖：

MongoDB
Redis
Socket.IO
长连接 / 实时事件
持久化状态

因此：

前端可以考虑上云函数
后端不建议按“纯云函数”思路部署

特别是如果你想把后端的 WebSocket / Socket.IO 服务也塞进 Vercel Functions 这类平台，通常会直接撞限制。Vercel 官方限制页明确说明：Vercel Functions 不支持充当 WebSocket 服务器。

相关文档：

Vercel Functions：https://vercel.com/docs/functions/
Vercel Limits（含 WebSockets 说明）：https://vercel.com/docs/limits/overview

21.8.2 云函数里错误使用 Docker 内网地址

在 Docker 部署里，你可以这样写：

CodeBlock Loading...

或者：

CodeBlock Loading...

但如果你把前端部署到云函数平台：

mx-core
host.docker.internal
172.17.0.1

这些地址通常都不可用。

此时应改成：

CodeBlock Loading...

或者改成你云函数平台能访问到的私网绝对地址 / 专线地址 / VPC 内地址，但必须是可解析、可访问的真实地址。

21.8.3 把 `API_URL` 写成相对路径，导致服务端请求报错

这个项目的服务端取 API 地址时，要求：

要么是绝对地址
要么必须能从请求上下文推导出 origin

如果你在云函数平台把：

CodeBlock Loading...

写成相对路径，那么某些 SSR / Route Handler / Server Fetch 场景下，就可能报出类似错误：

CodeBlock Loading...

因此云函数环境下建议统一使用：

CodeBlock Loading...

不要偷懒写相对路径。

21.8.4 只改了平台环境变量，但没重新触发部署

云函数平台里最常见的问题之一就是：

你在平台后台改了环境变量
以为线上会立刻生效
结果实际流量还是旧值

对 Next.js / Vercel 类平台，要特别注意：

NEXT_PUBLIC_* 一类变量经常会参与构建
改完环境变量后，必须重新部署
Preview / Production / Development 这三套环境也要分开核对

本项目里虽然还会通过页面注入 window.__ENV 暴露运行时变量，但你仍然应该遵守下面这个原则：

构建期需要的值，在构建前就准备好
运行期需要的值，在平台环境变量里补齐
改变量后重新部署

相关文档：

Next.js 环境变量：https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables
Vercel 环境变量：https://vercel.com/docs/environment-variables

21.8.5 Preview 环境、Production 环境变量混用

很多“明明本地没问题，上线就坏”的原因，不是代码错，而是环境混了。

最常见的是：

Production 里配了 NEXT_PUBLIC_API_URL
Preview 没配
Development 用的是本地 .env.local
WEBHOOK_SECRET 只在其中一套环境存在

结果就是：

预览环境接口请求 404 / 500
登录跳转错误
Webhook 验签失败
客户端能访问，SSR 却失败

建议你在云平台明确列出三套值：

Development
Preview
Production

并逐项核对以下变量：

NEXT_PUBLIC_API_URL
NEXT_PUBLIC_CLIENT_API_URL
NEXT_PUBLIC_GATEWAY_URL
API_URL
WEBHOOK_SECRET
TMDB_API_KEY
GH_TOKEN

21.8.6 把 `NEXT_PUBLIC_GATEWAY_URL` 配成前端域名

这个项目前端会用：

CodeBlock Loading...

拼出：

CodeBlock Loading...

去连 Socket.IO。

所以如果你错误配置成：

CodeBlock Loading...

而前端域名又没有把 /web 反向代理到后端，那么你就会看到：

WebSocket 握手失败
连接不断断开重连
在线人数 / 实时状态异常

21.8.7 云函数平台不适合承载 Socket.IO 服务端

再次强调一次，避免后续继续踩坑：

前端作为客户端连接 WebSocket，没有问题
后端如果要提供 /web Socket.IO 服务，应该放在真正的常驻服务上
不要把它当作“普通 HTTP API”一样塞进短生命周期云函数

如果你的目标是：

前端上云
后端仍然稳定支持评论、实时在线人数、活动推送

那么推荐做法是：

前端：云函数 / 静态托管 / 容器均可
后端：容器 / VM / K8s / 常驻 Node 服务

21.8.8 Edge Runtime 路由里混入 Node.js-only 代码

这个项目里已经有一部分路由明确声明为：

CodeBlock Loading...

例如：

某些代理接口
OG / 图片生成相关路由

如果你后续在这些路由里继续加入：

fs
path
原生 Node.js 模块
依赖本地文件系统的库
只能在 Node.js runtime 下工作的包

那么在云函数平台上很容易直接报错。

官方文档也明确说明：

Edge Runtime 只有一部分 Web API / Node API 子集
不是所有 Node.js 能力都可用

相关文档：

Next.js Route Segment Config：https://nextjs.org/docs/15/app/api-reference/file-conventions/route-segment-config
Next.js Edge Runtime：https://nextjs.org/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes
Vercel Edge Runtime：https://vercel.com/docs/concepts/functions/edge-functions/edge-runtime

21.8.9 Edge / Serverless 路由体积过大，或超时

云函数平台常见错误还包括：

函数包太大
某些字体 / 资源 / 依赖被一并打进函数
首次冷启动过慢
图片生成、远程抓取、聚合请求超时

而这个项目里本身就有：

OG 图生成
第三方 API 代理
聚合数据请求
多语言中间件

所以如果你在云函数平台继续叠加更多逻辑，要特别关注：

函数体积
最大执行时长
区域设置
冷启动

21.8.10 Middleware / 地理位置能力在不同平台表现不一样

这个项目的请求代理逻辑使用了：

@vercel/functions 的 geolocation
@vercel/functions 的 ipAddress

同时又兼容读取：

cf-ipcountry
cf-ipcity
cf-iplatitude
cf-iplongitude

也就是说：

在 Vercel 上，它会优先走 Vercel 的请求上下文
在 Cloudflare 一类平台上，可能走 cf-* 头
在其他平台上，这些值可能为空

因此你不能把：

地理位置
请求来源 IP

当作绝对可靠的部署前提，只能把它当作增强信息。

21.8.11 Webhook 地址指向了 Preview 域名或旧域名

很多人把前端上到云函数平台后，会出现：

页面能打开
后端内容更新后前端不刷新
文章重新发布后首页还是旧数据

通常原因不是“缓存坏了”，而是：

后端发 webhook 的地址还是旧域名
或者发到了 Preview 域名
或者 WEBHOOK_SECRET 前后不一致

正确做法：

后端 webhook 始终指向生产前端地址：

CodeBlock Loading...

生产环境前后端共享同一个 WEBHOOK_SECRET

21.8.12 第三方代理接口缺少密钥，线上才报 500

本项目前端内部还带了几个代理路由，常见包括：

GitHub 代理
TMDB 代理
Bangumi 代理

其中：

GH_TOKEN
TMDB_API_KEY

如果在云函数平台没配，最典型的结果就是：

本地可用
线上对应模块 500
某些页面局部报错但首页不一定全挂

所以部署后要主动检查这些功能点，而不是只看首页能不能打开。

21.8.13 推荐的云函数部署结论

如果你后面还想继续走云函数方案，建议直接记住下面这个结论：

前端可以部署到云函数平台
后端不要按纯云函数思路部署
API_URL 在云函数里必须是可访问的绝对地址
NEXT_PUBLIC_* 改完后要重新部署
NEXT_PUBLIC_GATEWAY_URL 必须指向真正的后端网关域名
WEBHOOK_SECRET、TMDB_API_KEY、GH_TOKEN 必须按环境完整配置
Preview / Production 的变量不能混

如果你只想要稳定省心，不想再被云函数配置反复折腾：

前端：可上云函数
后端：用 Docker 常驻部署

这就是这个项目最稳的组合。

22. 安全与隐私建议

22.1 不要提交这些内容

GH_TOKEN
TMDB_API_KEY
WEBHOOK_SECRET
JWT_SECRET
ENCRYPT_KEY
服务器 IP
个人域名
个人邮箱
Docker Hub 私有命名规则

22.2 环境变量文件权限

CodeBlock Loading...

22.3 Token 权限最小化

GH_PAT 只给源码读取权限
DOCKERHUB_TOKEN 只用于推镜像
第三方 API Key 不要复用管理员密钥

22.4 敏感信息分层

公开地址 -> build args
密钥 -> 服务器 env
数据库 -> 后端容器 env
反向代理 -> 站点配置，不写业务密钥

23. 推荐的最终部署方案

如果你要一个最稳、后续最好维护的方案，我建议：

后端 mx-core + mongo + redis 同机 Docker 部署
前端 yohaku-web 走 Docker Hub 镜像部署
前端和后端在同一个 Docker 网络
前端 API_URL=http://mx-core:2333/api/v2
浏览器侧始终走 https://<YOUR_API_DOMAIN>/api/v2
OpenResty / Nginx 只负责反向代理和 HTTPS
前端更新只重新构建镜像，不在服务器编译

这是当前仓库最适合的使用方式。

24. 最小可用上线清单

如果你只想快速上线，最少做这些事：

24.1 准备后端

CodeBlock Loading...

24.2 准备前端环境变量

CodeBlock Loading...

24.3 拉前端镜像并启动

CodeBlock Loading...

24.4 配反代

<YOUR_FRONTEND_DOMAIN> -> 127.0.0.1:2323
<YOUR_API_DOMAIN> -> 127.0.0.1:2333

24.5 验证

CodeBlock Loading...

25. 维护与更新流程

25.1 更新前端

CodeBlock Loading...

25.2 更新后端

CodeBlock Loading...

25.3 查看运行状态

CodeBlock Loading...

26. 最后说明

这份 Wiki 已经尽量覆盖：

当前部署仓库的真实用途
前端源码结构与本地开发
后端兼容栈的启动方式
前后端对接关系
Docker 化部署
GitHub Actions 自动构建
OpenResty / Nginx 反代
可直接复制的环境变量与配置模板
安全与隐私处理方式

如果你继续沿用这份文档，建议你保持一个原则：

所有公开文档只保留占位符，所有真实值只进服务器环境变量。

27. 官方链接索引（按场景分类）

为了方便你后续继续扩写这份 Wiki，这里再给一个集中索引版本。

28. 云函数 / Serverless 部署专项补充

这一节是给“曾经在云函数配置上反复出错”的情况单独准备的，你可以把它理解成部署前的强制核对清单。

28.1 什么时候适合上云函数

适合：

只部署前端
页面以 SSR / RSC / Route Handler 为主
后端已经在别处稳定运行
你接受 Preview / Production 多环境管理

不适合：

想把整个后端也一起塞进云函数
想在云函数里跑稳定 WebSocket 服务端
想依赖 Docker 内网地址互通
想“改个环境变量立刻生效但不重新部署”

28.2 云函数部署时必须满足的前提

前端必须能访问真实后端

CodeBlock Loading...

绝对不要在云函数里保留这些 Docker 写法

CodeBlock Loading...

28.3 云函数部署前的环境变量核对清单

生产环境至少确认：

NEXT_PUBLIC_API_URL
NEXT_PUBLIC_CLIENT_API_URL
NEXT_PUBLIC_GATEWAY_URL
API_URL
WEBHOOK_SECRET
TMDB_API_KEY
GH_TOKEN

如果是 Vercel 这类平台，再额外确认：

这些变量是否同时配置到了正确环境
是不是只配了 Preview 没配 Production
改完后是否重新触发了一次 Deployment

28.4 云函数版本的最小可用思路

推荐拓扑：

前端部署到云函数平台
后端继续放在容器 / 服务器
前端所有 API 和 WebSocket 都走后端公网域名
Webhook 从后端回调前端生产域名

28.5 如果你后续还要继续扩写 Wiki

建议你单独维护一个“云函数部署实录”附录，专门记录：

你实际使用的平台
哪些环境变量配错过
哪个报错最后对应哪一项配置
Preview 和 Production 的差异
Webhook / WebSocket / Edge Runtime 的特殊坑

这样后续每次迁移平台时，就不用再从头踩一次。

Yohaku 项目完整 Wiki

本文档基于当前仓库中的部署文件，以及上游前端 Yohaku / 兼容后端 MX Space Core 的公开代码结构整理而成。
所有示例都已做隐私脱敏：请把文中的占位符替换成你自己的值，不要直接把真实域名、用户名、Token、密钥写进 Git 仓库。

0. 官方链接与源项目入口

0.1 核心源项目入口

Yohaku 公共项目主页：https://github.com/Innei/Yohaku
MX Space Core 后端项目主页：https://github.com/mx-space/core

说明：你当前部署流程中实际使用的前端源码仓库可能是私有仓库，例如工作流里配置的私有 repository。
为避免把你的私有地址或权限信息写进 Wiki，这里统一只放公开项目主页；实际部署时请把它替换成你自己有权限访问的源码地址。

0.2 关键技术栈官方文档

Next.js 文档：https://nextjs.org/docs
React 文档：https://react.dev/
pnpm 安装与使用：https://pnpm.io/installation
Turborepo 文档：https://turborepo.dev/repo/docs
Tailwind CSS 文档：https://tailwindcss.com/docs/installation
TypeScript 文档：https://www.typescriptlang.org/docs/
Docker 文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/
GitHub Actions 文档：https://docs.github.com/actions
OpenResty 官网：https://openresty.org/en/
OpenResty 仓库：https://github.com/openresty/openresty
Nginx 文档：https://nginx.org/en/docs/
Socket.IO 文档：https://socket.io/docs/v4/
MongoDB 文档：https://www.mongodb.com/docs/
Redis 文档：https://redis.io/docs/latest/
Better Auth 文档：https://better-auth.com/docs/introduction
TMDB 开发者文档：https://developer.themoviedb.org/v3/reference/intro/getting-started
Git LFS 官网：https://git-lfs.com/

0.3 建议阅读顺序

如果你是第一次接手这个项目，建议按这个顺序阅读：

先看本文第 2、3 节，理解前后端拓扑和职责
再看第 8、9 节，完成本地开发或服务器搭建
然后看第 11、12 节，理解镜像构建和 CI/CD
最后看第 16、21、22 节，完成反代、安全和排障

1. 这份仓库是什么

当前这个本地仓库不是完整业务源码仓库，而是一个部署仓库，主要包含：

前端镜像构建用的 Dockerfile.hub
GitHub Actions 工作流 .github/workflows/dockerhub.yml
服务器侧部署文件 deploy/docker-compose.yml
服务器侧环境变量模板 deploy/yohaku.env.example
OpenResty / Nginx 反向代理示例（当前仓库中的 deploy/*.conf）

也就是说：

前端业务源码来自上游 Yohaku 项目
后端服务不是这个仓库的一部分，前端通过 API_URL / NEXT_PUBLIC_API_URL 去连接兼容的 CMS API

如果你只看当前仓库，可以把它理解为：

在 CI 或本地构建前端镜像
推送镜像到 Docker Hub
在服务器只做 docker pull + docker compose up -d
让前端通过环境变量去连接现有后端

2. 项目总体架构

2.1 逻辑拓扑

HTML

flowchart LR
    U["浏览器"] --> FQ["前端域名<br/><YOUR_FRONTEND_DOMAIN>"]
    FQ --> RP["OpenResty / Nginx"]
    RP --> FE["Yohaku 前端容器<br/>Next.js Standalone :2323"]

    U --> AQ["后端域名<br/><YOUR_API_DOMAIN>"]
    AQ --> ARP["OpenResty / Nginx"]
    ARP --> BE["MX Space Core / 兼容后端<br/>:2333"]

    FE -->|"SSR / Server Fetch<br/>API_URL"| BE
    U -->|"客户端请求<br/>NEXT_PUBLIC_API_URL"| BE
    U -->|"WebSocket<br/>NEXT_PUBLIC_GATEWAY_URL + /web"| BE
    BE -->|"Webhook 回调"| FE
    FE -->|"代理第三方 API"| GH["GitHub / TMDB 等第三方服务"]

CodeBlock Loading...

2.2 端口约定

建议统一约定如下：

前端容器：2323
后端容器：2333
前端公网入口：https://<YOUR_FRONTEND_DOMAIN>
后端公网入口：https://<YOUR_API_DOMAIN>

2.3 当前方案的关键思想

浏览器可见的地址走公网域名
前端 SSR 访问后端优先走内网地址 API_URL
密钥类变量只放服务器，不放镜像
前端更新只需要重建镜像，不需要在服务器源码编译

3. 前后端职责划分

3.1 前端（Yohaku）

前端是一个 pnpm + turbo 的 monorepo，主应用是：

TEXT

apps/web

CodeBlock Loading...

核心技术栈：

Node.js >= 20
pnpm 10.27.0
Turbo Repo
Next.js 16
React 19
Tailwind CSS 4
output: standalone 方式打包

前端相关官方入口：

项目主页：https://github.com/Innei/Yohaku
Next.js 文档：https://nextjs.org/docs
React 文档：https://react.dev/
pnpm 文档：https://pnpm.io/installation
Turborepo 文档：https://turborepo.dev/repo/docs
Tailwind CSS 文档：https://tailwindcss.com/docs/installation
TypeScript 文档：https://www.typescriptlang.org/docs/

前端主要负责：

页面渲染（SSR / RSC / 客户端交互）
多语言路由
评论、文章、页面、说说、时间线等页面展示
Webhook 触发的页面再验证
代理 GitHub / TMDB 等第三方接口
通过 WebSocket 接收实时事件

3.2 后端（MX Space Core / 兼容实现）

从前端依赖和官方后端公开信息看，兼容后端一般具备：

Node.js >= 22
NestJS
MongoDB 7
Redis 7
Socket.IO
Better Auth / OAuth / Passkey
REST API（/api/v2）
WebSocket 网关（/web）

后端与基础设施官方入口：

后端项目主页：https://github.com/mx-space/core
MongoDB 文档：https://www.mongodb.com/docs/
Redis 文档：https://redis.io/docs/latest/
Socket.IO 文档：https://socket.io/docs/v4/
Better Auth 文档：https://better-auth.com/docs/introduction

后端主要负责：

内容管理：文章、页面、笔记、分类、评论、项目等
聚合接口：站点信息、聚合首页数据
认证接口：/auth
实时推送：Socket.IO
回调前端 /api/webhook 触发缓存失效与再验证

4. 目录说明

4.1 当前部署仓库

TEXT

.
├── Dockerfile.hub
├── 历史部署说明文档
├── .github/workflows/dockerhub.yml
└── deploy
    ├── docker-compose.yml
    ├── 站点反向代理配置示例
    └── yohaku.env.example

CodeBlock Loading...

4.2 前端上游源码仓库（逻辑结构）

TEXT

Yohaku/
├── apps/
│   └── web/                 # Next.js 前端主应用
├── packages/               # 共享包
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

CodeBlock Loading...

4.3 后端兼容仓库（逻辑结构）

TEXT

mx-core/
├── apps/core/              # NestJS 主应用
├── packages/api-client/    # 前端使用的 API SDK
├── packages/webhook/       # Webhook SDK
├── docker-compose.yml
└── docker-compose.server.yml

CodeBlock Loading...

5. 你需要先准备什么

5.1 本地开发机

建议安装：

Node.js 20.x（前端）
Node.js 22.x（如果你也要跑后端源码）
corepack
pnpm
git
git-lfs
docker
docker compose

macOS 示例：

BASH

brew install node git git-lfs
corepack enable
git lfs install

CodeBlock Loading...

Ubuntu / Debian 示例：

BASH

sudo apt update
sudo apt install -y git git-lfs curl docker.io docker-compose-plugin
corepack enable
git lfs install

CodeBlock Loading...

5.2 服务器

建议准备一台 Linux 服务器，并安装：

Docker
Docker Compose Plugin
OpenResty 或 Nginx
域名与 HTTPS 证书

建议目录：

BASH

sudo mkdir -p /opt/yohaku
sudo mkdir -p /opt/yohaku-env
sudo mkdir -p /opt/mx-space
sudo mkdir -p /opt/mx-space/data

CodeBlock Loading...

6. 域名、路径、镜像命名建议

为避免文档里出现真实信息，全文统一使用下列占位符：

占位符	含义	示例
`<YOUR_FRONTEND_DOMAIN>`	前端域名	`blog.example.com`
`<YOUR_API_DOMAIN>`	后端 API / 网关域名	`api.example.com`
`<YOUR_DOCKERHUB_USERNAME>`	Docker Hub 用户名	`yourname`
`<YOUR_SOURCE_REPO>`	前端源码仓库	`owner/Yohaku`
`<BACKEND_INTERNAL_HOST>`	前端容器访问后端的内网主机名	`mx-core`
`<YOUR_GITHUB_TOKEN>`	GitHub Token	`ghp_xxx`
`<YOUR_TMDB_API_KEY>`	TMDB Token / API Key	`xxx`

推荐映射：

前端公网域名：https://<YOUR_FRONTEND_DOMAIN>
后端公网域名：https://<YOUR_API_DOMAIN>
前端镜像：<YOUR_DOCKERHUB_USERNAME>/yohaku-web:latest
服务器前端目录：/opt/yohaku
服务器前端环境变量：/opt/yohaku-env/yohaku.env
服务器后端目录：/opt/mx-space

7. 环境变量总表

7.1 前端公开构建变量

这些变量最终会暴露到浏览器，可以写进构建参数：

变量名	是否必须	说明	示例
`NEXT_PUBLIC_API_URL`	是	浏览器请求 API 的公开地址	`https://<YOUR_API_DOMAIN>/api/v2`
`NEXT_PUBLIC_CLIENT_API_URL`	建议	浏览器侧单独指定 API 地址	`https://<YOUR_API_DOMAIN>/api/v2`
`NEXT_PUBLIC_GATEWAY_URL`	是	WebSocket / 网关地址，不带 `/web`	`https://<YOUR_API_DOMAIN>`

7.2 前端运行时变量

这些变量不要写死进镜像：

变量名	是否必须	说明	示例
`API_URL`	强烈建议	前端 SSR 访问后端的内网地址	`http://mx-core:2333/api/v2`
`WEBHOOK_SECRET`	建议	前端 `/api/webhook` 验签密钥	随机字符串
`TMDB_API_KEY`	可选	前端 TMDB 代理接口使用	`xxx`
`GH_TOKEN`	可选	前端 GitHub 代理接口使用	`ghp_xxx`
`NODE_ENV`	是	环境模式	`production`
`HOSTNAME`	是	监听地址	`0.0.0.0`
`PORT`	是	前端监听端口	`2323`

7.3 后端核心变量

后端常见最小集：

变量名	是否必须	说明	示例
`JWT_SECRET`	是	JWT 签名密钥	随机字符串
`ALLOWED_ORIGINS`	是	允许跨域来源	`<YOUR_FRONTEND_DOMAIN>,www.<YOUR_FRONTEND_DOMAIN>`
`ENCRYPT_KEY`	建议	字段加密密钥，64 位十六进制	`openssl rand -hex 32`
`ENCRYPT_ENABLE`	建议	是否启用加密	`false`
`DB_CONNECTION_STRING` / `MONGO_CONNECTION`	是	MongoDB 连接串	`mongodb://mongo:27017/mx-space`
`REDIS_HOST`	是	Redis 主机	`redis`
`REDIS_PORT`	是	Redis 端口	`6379`
`PORT`	是	后端端口	`2333`
`TZ`	建议	时区	`Asia/Shanghai`

7.4 建议的密钥生成命令

BASH

# 64 位十六进制，适合 ENCRYPT_KEY
openssl rand -hex 32

# 适合 JWT_SECRET / WEBHOOK_SECRET
openssl rand -base64 48

CodeBlock Loading...

8. 前端本地开发搭建

如果你只是做部署，不一定要本地跑源码；但如果你要改主题、页面、文案、交互，就建议按这一节完整搭建。

8.1 拉取前端源码

BASH

git clone https://github.com/<YOUR_SOURCE_REPO>.git
cd Yohaku
git lfs install
git lfs pull

CodeBlock Loading...

如果源码仓库是私有的：

BASH

git clone https://github.com/<YOUR_SOURCE_REPO>.git
cd Yohaku
git lfs checkout

CodeBlock Loading...

8.2 启用 pnpm

BASH

corepack enable
corepack use pnpm@10.27.0
pnpm -v

CodeBlock Loading...

8.3 安装依赖

BASH

pnpm install --frozen-lockfile

CodeBlock Loading...

8.4 配置前端本地环境变量

可以在 apps/web/.env.local 写入：

ENV

NODE_ENV=development
HOSTNAME=0.0.0.0
PORT=2323

NEXT_PUBLIC_API_URL=http://127.0.0.1:2333/api/v2
NEXT_PUBLIC_CLIENT_API_URL=http://127.0.0.1:2333/api/v2
NEXT_PUBLIC_GATEWAY_URL=http://127.0.0.1:2333

# 本地开发一般直接走同一个地址即可
API_URL=http://127.0.0.1:2333/api/v2

# 可选
TMDB_API_KEY=
GH_TOKEN=
WEBHOOK_SECRET=dev_only_secret

CodeBlock Loading...

8.5 启动前端

在仓库根目录运行：

BASH

pnpm dev

CodeBlock Loading...

或者只启动前端应用：

BASH

pnpm --filter @shiro/web dev

CodeBlock Loading...

默认访问：

TEXT

http://127.0.0.1:2323

CodeBlock Loading...

8.6 本地前端构建

BASH

pnpm --filter @shiro/web build:ci

CodeBlock Loading...

如果要验证 standalone 产物，通常会在构建后运行：

BASH

node apps/web/server.js

CodeBlock Loading...

实际生产镜像里运行的也是这个入口。

8.7 前端开发阶段可参考的官方链接

Next.js 路由、SSR、RSC、部署说明：https://nextjs.org/docs
React 新文档与 Hooks 说明：https://react.dev/
pnpm Workspace / 安装说明：https://pnpm.io/installation
Turborepo Monorepo 任务说明：https://turborepo.dev/repo/docs
Tailwind CSS 安装与配置：https://tailwindcss.com/docs/installation
TypeScript Handbook：https://www.typescriptlang.org/docs/

9. 后端本地 / 服务器搭建

这一节给两种方式：
方式 A：跑兼容后端源码
方式 B：直接用官方镜像起服务

9.1 方式 A：从源码启动后端

BASH

git clone https://github.com/mx-space/core.git
cd core

corepack enable
pnpm install

docker compose up -d mongo redis
pnpm dev

CodeBlock Loading...

后端默认端口：

TEXT

http://127.0.0.1:2333

CodeBlock Loading...

健康检查：

BASH

curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

如果正常，通常应返回：

JSON

{"data":"pong"}

CodeBlock Loading...

9.2 方式 B：用 Docker 直接部署后端

在 /opt/mx-space 下创建 .env：

ENV

JWT_SECRET=<GENERATE_A_STRONG_JWT_SECRET>
ALLOWED_ORIGINS=<YOUR_FRONTEND_DOMAIN>,www.<YOUR_FRONTEND_DOMAIN>

ENCRYPT_KEY=<GENERATE_64_HEX_KEY>
ENCRYPT_ENABLE=false

CDN_CACHE_HEADER=true
FORCE_CACHE_HEADER=false

MONGO_CONNECTION=

THROTTLE_TTL=10
THROTTLE_LIMIT=20

CodeBlock Loading...

然后创建 /opt/mx-space/docker-compose.yml：

YAML

services:
  mx-core:
    image: innei/mx-server:latest
    container_name: mx-core
    restart: unless-stopped
    ports:
      - "2333:2333"
    environment:
      TZ: Asia/Shanghai
      PORT: "2333"
      ALLOWED_ORIGINS: ${ALLOWED_ORIGINS}
      DB_CONNECTION_STRING: mongodb://mongo:27017/mx-space
      REDIS_HOST: redis
      REDIS_PORT: "6379"
      ENCRYPT_ENABLE: ${ENCRYPT_ENABLE}
      ENCRYPT_KEY: ${ENCRYPT_KEY}
      JWT_SECRET: ${JWT_SECRET}
      DISABLE_CACHE: "false"
    volumes:
      - ./data/mx-space:/root/.mx-space
    depends_on:
      - mongo
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:2333/api/v2/ping"]
      interval: 1m30s
      timeout: 30s
      retries: 5
      start_period: 30s

  redis:
    image: redis:7-alpine
    container_name: mx-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s

  mongo:
    image: mongo:7
    container_name: mx-mongo
    restart: unless-stopped
    command: ["mongod", "--bind_ip_all"]
    volumes:
      - ./data/db:/data/db

CodeBlock Loading...

启动：

BASH

cd /opt/mx-space
docker compose --env-file .env up -d
docker compose ps
curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

9.3 后端搭建阶段可参考的官方链接

MX Space Core 项目页：https://github.com/mx-space/core
MongoDB 官方文档：https://www.mongodb.com/docs/
Redis 官方文档：https://redis.io/docs/latest/
Socket.IO 文档：https://socket.io/docs/v4/
Better Auth 文档：https://better-auth.com/docs/introduction

10. 前端对后端的接口约定

这部分很重要，因为前端能不能跑起来，核心就在这里。

10.1 浏览器请求 API

浏览器端主要看：

ENV

NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2

CodeBlock Loading...

10.2 前端 SSR 请求 API

服务端渲染时，前端优先读取：

ENV

API_URL=http://mx-core:2333/api/v2

CodeBlock Loading...

也就是说：

浏览器访问：走公网域名
容器内部访问：走 Docker 内网主机名

这是最推荐的生产拓扑。

10.3 WebSocket 地址

前端会把：

ENV

NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>

CodeBlock Loading...

拼成：

TEXT

https://<YOUR_API_DOMAIN>/web

CodeBlock Loading...

并通过 Socket.IO WebSocket 连接。

所以你的后端反向代理必须允许：

Upgrade
Connection
长连接超时

10.4 Auth 地址

前端认证客户端会把：

TEXT

${API_URL}/auth

CodeBlock Loading...

作为认证基地址，所以后端需要兼容：

TEXT

https://<YOUR_API_DOMAIN>/api/v2/auth

CodeBlock Loading...

10.5 Webhook 地址

后端内容变更后，应回调前端：

TEXT

https://<YOUR_FRONTEND_DOMAIN>/api/webhook

CodeBlock Loading...

并使用与前端一致的：

ENV

WEBHOOK_SECRET

CodeBlock Loading...

完成签名验证。

11. 当前仓库的前端镜像构建方式

当前仓库采用：

GitHub Actions 拉取源码
用 Dockerfile.hub 构建
推送到 Docker Hub

11.1 `Dockerfile.hub` 的作用

它做了几件事：

安装 Node / pnpm / sharp
安装依赖
执行 pnpm --filter @shiro/web build:ci
将 Next.js standalone 产物复制到最终镜像
安装中文和英文字体
暴露 2323
运行 node apps/web/server.js

11.2 建议保留的 `Dockerfile.hub`

下面这份是可直接使用的隐私安全模板：

DOCKERFILE

FROM node:20-alpine AS base

RUN npm install -g --arch=x64 --platform=linux sharp pnpm@10.27.0

FROM base AS deps

RUN apk add --no-cache libc6-compat python3 make g++

WORKDIR /app
COPY . .

RUN pnpm install --frozen-lockfile

FROM base AS builder

RUN apk add --no-cache git

WORKDIR /app
COPY --from=deps /app/ .

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

ARG NEXT_PUBLIC_API_URL
ARG NEXT_PUBLIC_CLIENT_API_URL
ARG NEXT_PUBLIC_GATEWAY_URL

ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
ENV NEXT_PUBLIC_CLIENT_API_URL=${NEXT_PUBLIC_CLIENT_API_URL}
ENV NEXT_PUBLIC_GATEWAY_URL=${NEXT_PUBLIC_GATEWAY_URL}

RUN pnpm --filter @shiro/web build:ci

FROM base AS runner

WORKDIR /app

ENV NODE_ENV=production
ENV PORT=2323
ENV HOSTNAME=0.0.0.0
ENV NEXT_SHARP_PATH=/usr/local/lib/node_modules/sharp

RUN apk add --no-cache fontconfig wget curl unzip \
 && mkdir -p /usr/share/fonts/truetype/chinese /usr/share/fonts/truetype/english

RUN wget -O /usr/share/fonts/truetype/LXGWWenKai-Regular.ttf \
    https://github.com/lxgw/LxgwWenKai/releases/download/v1.520/LXGWWenKai-Regular.ttf
RUN wget -O /usr/share/fonts/truetype/LXGWWenKai-Medium.ttf \
    https://github.com/lxgw/LxgwWenKai/releases/download/v1.520/LXGWWenKai-Medium.ttf
RUN wget -O /usr/share/fonts/truetype/LXGWWenKai-Light.ttf \
    https://github.com/lxgw/LxgwWenKai/releases/download/v1.520/LXGWWenKai-Light.ttf

RUN wget -O /tmp/geist.zip \
    https://github.com/vercel/geist-font/releases/download/1.5.0/geist-font-1.5.0.zip
RUN unzip /tmp/geist.zip -d /tmp/geist
RUN find /tmp/geist -name "*.ttf" -exec cp {} /usr/share/fonts/truetype/ \;
RUN rm -rf /tmp/geist.zip /tmp/geist
RUN fc-cache -fv

COPY --from=builder /app/apps/web/public ./apps/web/public
COPY --from=builder /app/apps/web/.next/standalone ./
COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=builder /app/apps/web/.next/server ./apps/web/.next/server

EXPOSE 2323

CMD ["node", "apps/web/server.js"]

CodeBlock Loading...

11.3 镜像构建相关官方文档

Docker 官方文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/
Next.js 部署与构建文档：https://nextjs.org/docs

12. GitHub Actions 自动构建镜像

12.1 需要的 GitHub Secrets

在你的部署仓库中配置：

GH_PAT
- 用于读取前端源码仓库
DOCKERHUB_USERNAME
- Docker Hub 用户名
DOCKERHUB_TOKEN
- Docker Hub Access Token

12.2 推荐的工作流文件

保存为 .github/workflows/dockerhub.yml：

YAML

name: Build And Push Yohaku Image

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  docker:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout deploy repo
        uses: actions/checkout@v4

      - name: Checkout Yohaku source
        uses: actions/checkout@v4
        with:
          repository: <YOUR_SOURCE_REPO>
          token: ${{ secrets.GH_PAT }}
          fetch-depth: 1
          lfs: true
          path: app

      - name: Checkout LFS objects
        working-directory: app
        run: git lfs checkout

      - name: Copy Dockerfile into source tree
        run: cp Dockerfile.hub app/Dockerfile.hub

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ secrets.DOCKERHUB_USERNAME }}/yohaku-web
          tags: |
            type=raw,value=latest
            type=sha,prefix=

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: ./app
          file: ./app/Dockerfile.hub
          platforms: linux/amd64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
            NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2
            NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>

CodeBlock Loading...

12.3 首次触发

BASH

git add .
git commit -m "add yohaku deploy workflow"
git push

CodeBlock Loading...

然后在 GitHub 仓库中：

TEXT

Actions -> Build And Push Yohaku Image -> Run workflow

CodeBlock Loading...

12.4 GitHub Actions 相关官方文档

GitHub Actions 总文档：https://docs.github.com/actions
Docker 官方文档：https://docs.docker.com/
Docker Hub 文档：https://docs.docker.com/docker-hub/

13. 前端生产环境变量文件

将以下内容保存为服务器上的：

TEXT

/opt/yohaku-env/yohaku.env

CodeBlock Loading...

推荐模板如下：

ENV

NODE_ENV=production
HOSTNAME=0.0.0.0
PORT=2323

# 浏览器请求的公开 API
NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2

# WebSocket / Gateway 根地址
NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>

# SSR / RSC / Server Actions 从容器内部访问后端
# 若前后端在同一个 docker compose 网络内，优先使用服务名
API_URL=http://mx-core:2333/api/v2

# 可选功能
WEBHOOK_SECRET=<GENERATE_A_STRONG_SECRET>
TMDB_API_KEY=<YOUR_TMDB_API_KEY>
GH_TOKEN=<YOUR_GITHUB_TOKEN>

CodeBlock Loading...

13.1 如果后端不在同一个 Docker 网络

如果后端不在同一个 compose 网络，而是在宿主机上跑，可以改成：

ENV

API_URL=http://host.docker.internal:2333/api/v2

CodeBlock Loading...

Linux 若 host.docker.internal 不通，可尝试：

ENV

API_URL=http://172.17.0.1:2333/api/v2

CodeBlock Loading...

但最佳实践仍然是前后端放在同一个 Docker 网络，直接用服务名互通。

14. 前端服务器部署（只部署前端）

如果你的后端已经跑好了，那么前端可以单独部署。

14.1 `/opt/yohaku/docker-compose.yml`

YAML

services:
  yohaku-web:
    image: <YOUR_DOCKERHUB_USERNAME>/yohaku-web:latest
    platform: linux/amd64
    container_name: yohaku-web
    restart: unless-stopped
    ports:
      - "2323:2323"
    env_file:
      - /opt/yohaku-env/yohaku.env
    extra_hosts:
      - "host.docker.internal:host-gateway"

CodeBlock Loading...

14.2 启动命令

BASH

cd /opt/yohaku
docker compose pull
docker compose up -d
docker compose ps
docker logs -f yohaku-web

CodeBlock Loading...

15. 一体化部署（前后端同机同网）

如果你希望前后端一起放在一台服务器上，推荐直接用下面这个组合版 docker-compose.yml。

保存为：

TEXT

/opt/yohaku/docker-compose.full.yml

CodeBlock Loading...

YAML

services:
  yohaku-web:
    image: <YOUR_DOCKERHUB_USERNAME>/yohaku-web:latest
    container_name: yohaku-web
    restart: unless-stopped
    ports:
      - "2323:2323"
    env_file:
      - /opt/yohaku-env/yohaku.env
    depends_on:
      - mx-core

  mx-core:
    image: innei/mx-server:latest
    container_name: mx-core
    restart: unless-stopped
    ports:
      - "2333:2333"
    environment:
      TZ: Asia/Shanghai
      PORT: "2333"
      ALLOWED_ORIGINS: <YOUR_FRONTEND_DOMAIN>,www.<YOUR_FRONTEND_DOMAIN>
      DB_CONNECTION_STRING: mongodb://mongo:27017/mx-space
      REDIS_HOST: redis
      REDIS_PORT: "6379"
      ENCRYPT_ENABLE: "false"
      ENCRYPT_KEY: <GENERATE_64_HEX_KEY>
      JWT_SECRET: <GENERATE_A_STRONG_JWT_SECRET>
      DISABLE_CACHE: "false"
    volumes:
      - /opt/mx-space/data/mx-space:/root/.mx-space
    depends_on:
      - mongo
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:2333/api/v2/ping"]
      interval: 1m30s
      timeout: 30s
      retries: 5
      start_period: 30s

  redis:
    image: redis:7-alpine
    container_name: mx-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - /opt/mx-space/data/redis:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s

  mongo:
    image: mongo:7
    container_name: mx-mongo
    restart: unless-stopped
    command: ["mongod", "--bind_ip_all"]
    volumes:
      - /opt/mx-space/data/db:/data/db

CodeBlock Loading...

15.1 组合部署时前端 env 要这样写

ENV

NODE_ENV=production
HOSTNAME=0.0.0.0
PORT=2323

NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>

API_URL=http://mx-core:2333/api/v2

WEBHOOK_SECRET=<GENERATE_A_STRONG_SECRET>
TMDB_API_KEY=<YOUR_TMDB_API_KEY>
GH_TOKEN=<YOUR_GITHUB_TOKEN>

CodeBlock Loading...

15.2 启动组合部署

BASH

cd /opt/yohaku
docker compose -f docker-compose.full.yml up -d
docker compose -f docker-compose.full.yml ps

CodeBlock Loading...

16. OpenResty / Nginx 反向代理

生产环境至少需要两套反代：
前端域名 -> 127.0.0.1:2323
后端域名 -> 127.0.0.1:2333

16.1 前端站点配置

保存为：

TEXT

/etc/nginx/conf.d/<YOUR_FRONTEND_DOMAIN>.conf

CodeBlock Loading...

NGINX

server {
    listen 80;
    server_name <YOUR_FRONTEND_DOMAIN>;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:2323;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

CodeBlock Loading...

16.2 后端站点配置（含 WebSocket）

保存为：

TEXT

/etc/nginx/conf.d/<YOUR_API_DOMAIN>.conf

CodeBlock Loading...

NGINX

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name <YOUR_API_DOMAIN>;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:2333;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

CodeBlock Loading...

16.3 HTTPS

建议通过：

1Panel
Certbot
acme.sh
云厂商证书托管

为这两个域名都签发 HTTPS。

如果使用 1Panel，原则上就是：

站点 A：<YOUR_FRONTEND_DOMAIN> -> 127.0.0.1:2323
站点 B：<YOUR_API_DOMAIN> -> 127.0.0.1:2333

并开启 WebSocket 支持。

16.4 反向代理与网关参考链接

OpenResty 官网：https://openresty.org/en/
OpenResty 仓库：https://github.com/openresty/openresty
Nginx 官方文档：https://nginx.org/en/docs/
Socket.IO 文档（排查 WebSocket / Upgrade 问题时很有用）：https://socket.io/docs/v4/

17. 本地手工构建并推送前端镜像

如果你暂时不想走 GitHub Actions，可以本地推镜像。

在前端源码根目录执行：

BASH

docker login

docker buildx build \
  --platform linux/amd64 \
  -f Dockerfile.hub \
  --build-arg NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2 \
  --build-arg NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2 \
  --build-arg NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN> \
  -t <YOUR_DOCKERHUB_USERNAME>/yohaku-web:latest \
  --push \
  .

CodeBlock Loading...

18. 服务器上线顺序

推荐按这个顺序操作：

18.1 先起后端

BASH

cd /opt/mx-space
docker compose up -d
curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

18.2 再起前端

BASH

cd /opt/yohaku
docker compose pull
docker compose up -d
curl http://127.0.0.1:2323/api/healthz

CodeBlock Loading...

18.3 最后接入反向代理

BASH

sudo nginx -t
sudo systemctl reload nginx

CodeBlock Loading...

19. 上线后检查清单

19.1 检查前端容器

BASH

docker ps | grep yohaku-web
docker logs --tail=200 yohaku-web

CodeBlock Loading...

19.2 检查后端容器

BASH

docker ps | grep mx-core
docker logs --tail=200 mx-core

CodeBlock Loading...

19.3 检查前端健康接口

BASH

curl http://127.0.0.1:2323/api/healthz

CodeBlock Loading...

应返回类似：

JSON

{"message":"OK"}

CodeBlock Loading...

19.4 检查后端健康接口

BASH

curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

19.5 检查前端容器内是否能访问后端

如果是组合部署：

BASH

docker exec -it yohaku-web sh
wget -qO- http://mx-core:2333/api/v2/ping

CodeBlock Loading...

如果是宿主机互通：

BASH

docker exec -it yohaku-web sh
wget -qO- http://host.docker.internal:2333/api/v2/ping

CodeBlock Loading...

19.6 浏览器检查

浏览器打开：

TEXT

https://<YOUR_FRONTEND_DOMAIN>

CodeBlock Loading...

重点看：

首页是否能打开
文章 / 页面 / 说说是否能加载
控制台是否存在 CORS 报错
WebSocket 是否连接成功
登录 / 评论 / 搜索是否正常

20. Webhook 配置建议

前端存在：

TEXT

/api/webhook

CodeBlock Loading...

它会处理内容更新事件，并触发页面再验证。

20.1 需要保证

后端和前端共享同一个 WEBHOOK_SECRET
后端把内容更新事件发送到：

TEXT

https://<YOUR_FRONTEND_DOMAIN>/api/webhook

CodeBlock Loading...

20.2 健康检查类型

前端 webhook 路由支持 health_check 类型事件，并会返回：

TEXT

OK

CodeBlock Loading...

21. 常见故障排查

21.1 首页能开，但内容为空

通常是：

API_URL 错了
后端没起来
容器内访问不到后端

排查：

BASH

docker exec -it yohaku-web sh
env | grep API_URL
wget -qO- http://mx-core:2333/api/v2/ping

CodeBlock Loading...

21.2 浏览器请求报跨域

通常是后端：

ENV

ALLOWED_ORIGINS

CodeBlock Loading...

没包含前端域名。

建议设置为：

ENV

ALLOWED_ORIGINS=<YOUR_FRONTEND_DOMAIN>,www.<YOUR_FRONTEND_DOMAIN>

CodeBlock Loading...

21.3 WebSocket 连不上

通常是：

NEXT_PUBLIC_GATEWAY_URL 错了
后端反代没开 WebSocket Upgrade
后端域名证书问题

检查：

浏览器 Network -> WS
Nginx Upgrade / Connection 头
后端 /web 是否由反代正确转发

21.4 `host.docker.internal` 不通

解决顺序：

优先把前后端放在一个 compose 网络，用服务名访问
如果必须跨宿主机，Linux 再尝试 172.17.0.1
最后才考虑额外网桥配置

21.5 构建时报 `git-lfs` 相关错误

安装并初始化：

BASH

git lfs install
git lfs pull

CodeBlock Loading...

GitHub Actions 中确保：

YAML

lfs: true

CodeBlock Loading...

并执行：

BASH

git lfs checkout

CodeBlock Loading...

21.6 `pnpm install --frozen-lockfile` 失败

通常是 pnpm 版本不匹配。

修复：

BASH

corepack use pnpm@10.27.0
pnpm -v

CodeBlock Loading...

21.7 排障时常用官方入口

pnpm 文档：https://pnpm.io/installation
Docker 文档：https://docs.docker.com/
GitHub Actions 文档：https://docs.github.com/actions
Nginx 文档：https://nginx.org/en/docs/
OpenResty 官网：https://openresty.org/en/
Git LFS 官网：https://git-lfs.com/

21.8 云函数 / Serverless 配置反复出错时，优先检查这些点

这一节是根据本项目代码结构、前后端运行方式，以及 Next.js / Vercel 类平台的运行特征整理的。
如果你之前在“云函数配置”这里反复出错，大概率就是下面这些配置项没有对齐。

21.8.1 把前端能上云函数，误以为后端也能完整上云函数

这个项目的前端是 Next.js，理论上可以部署到支持 Next.js 的云函数 / Serverless 平台。
但后端兼容实现 MX Space Core 依赖：

MongoDB
Redis
Socket.IO
长连接 / 实时事件
持久化状态

因此：

前端可以考虑上云函数
后端不建议按“纯云函数”思路部署

相关文档：

Vercel Functions：https://vercel.com/docs/functions/
Vercel Limits（含 WebSockets 说明）：https://vercel.com/docs/limits/overview

21.8.2 云函数里错误使用 Docker 内网地址

在 Docker 部署里，你可以这样写：

ENV

API_URL=http://mx-core:2333/api/v2

CodeBlock Loading...

或者：

ENV

API_URL=http://host.docker.internal:2333/api/v2

CodeBlock Loading...

但如果你把前端部署到云函数平台：

mx-core
host.docker.internal
172.17.0.1

这些地址通常都不可用。

此时应改成：

ENV

API_URL=https://<YOUR_API_DOMAIN>/api/v2

CodeBlock Loading...

或者改成你云函数平台能访问到的私网绝对地址 / 专线地址 / VPC 内地址，但必须是可解析、可访问的真实地址。

21.8.3 把 `API_URL` 写成相对路径，导致服务端请求报错

这个项目的服务端取 API 地址时，要求：

要么是绝对地址
要么必须能从请求上下文推导出 origin

如果你在云函数平台把：

ENV

API_URL=/api/v2

CodeBlock Loading...

写成相对路径，那么某些 SSR / Route Handler / Server Fetch 场景下，就可能报出类似错误：

TEXT

Relative API base URL "/api/v2" requires a request origin

CodeBlock Loading...

因此云函数环境下建议统一使用：

ENV

API_URL=https://<YOUR_API_DOMAIN>/api/v2

CodeBlock Loading...

不要偷懒写相对路径。

21.8.4 只改了平台环境变量，但没重新触发部署

云函数平台里最常见的问题之一就是：

你在平台后台改了环境变量
以为线上会立刻生效
结果实际流量还是旧值

对 Next.js / Vercel 类平台，要特别注意：

NEXT_PUBLIC_* 一类变量经常会参与构建
改完环境变量后，必须重新部署
Preview / Production / Development 这三套环境也要分开核对

本项目里虽然还会通过页面注入 window.__ENV 暴露运行时变量，但你仍然应该遵守下面这个原则：

构建期需要的值，在构建前就准备好
运行期需要的值，在平台环境变量里补齐
改变量后重新部署

相关文档：

Next.js 环境变量：https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables
Vercel 环境变量：https://vercel.com/docs/environment-variables

21.8.5 Preview 环境、Production 环境变量混用

很多“明明本地没问题，上线就坏”的原因，不是代码错，而是环境混了。

最常见的是：

Production 里配了 NEXT_PUBLIC_API_URL
Preview 没配
Development 用的是本地 .env.local
WEBHOOK_SECRET 只在其中一套环境存在

结果就是：

预览环境接口请求 404 / 500
登录跳转错误
Webhook 验签失败
客户端能访问，SSR 却失败

建议你在云平台明确列出三套值：

Development
Preview
Production

并逐项核对以下变量：

NEXT_PUBLIC_API_URL
NEXT_PUBLIC_CLIENT_API_URL
NEXT_PUBLIC_GATEWAY_URL
API_URL
WEBHOOK_SECRET
TMDB_API_KEY
GH_TOKEN

21.8.6 把 `NEXT_PUBLIC_GATEWAY_URL` 配成前端域名

这个项目前端会用：

ENV

NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>

CodeBlock Loading...

拼出：

TEXT

https://<YOUR_API_DOMAIN>/web

CodeBlock Loading...

去连 Socket.IO。

所以如果你错误配置成：

ENV

NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_FRONTEND_DOMAIN>

CodeBlock Loading...

而前端域名又没有把 /web 反向代理到后端，那么你就会看到：

WebSocket 握手失败
连接不断断开重连
在线人数 / 实时状态异常

21.8.7 云函数平台不适合承载 Socket.IO 服务端

再次强调一次，避免后续继续踩坑：

前端作为客户端连接 WebSocket，没有问题
后端如果要提供 /web Socket.IO 服务，应该放在真正的常驻服务上
不要把它当作“普通 HTTP API”一样塞进短生命周期云函数

如果你的目标是：

前端上云
后端仍然稳定支持评论、实时在线人数、活动推送

那么推荐做法是：

前端：云函数 / 静态托管 / 容器均可
后端：容器 / VM / K8s / 常驻 Node 服务

21.8.8 Edge Runtime 路由里混入 Node.js-only 代码

这个项目里已经有一部分路由明确声明为：

export const runtime = 'edge'

CodeBlock Loading...

例如：

某些代理接口
OG / 图片生成相关路由

如果你后续在这些路由里继续加入：

fs
path
原生 Node.js 模块
依赖本地文件系统的库
只能在 Node.js runtime 下工作的包

那么在云函数平台上很容易直接报错。

官方文档也明确说明：

Edge Runtime 只有一部分 Web API / Node API 子集
不是所有 Node.js 能力都可用

相关文档：

Next.js Route Segment Config：https://nextjs.org/docs/15/app/api-reference/file-conventions/route-segment-config
Next.js Edge Runtime：https://nextjs.org/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes
Vercel Edge Runtime：https://vercel.com/docs/concepts/functions/edge-functions/edge-runtime

21.8.9 Edge / Serverless 路由体积过大，或超时

云函数平台常见错误还包括：

函数包太大
某些字体 / 资源 / 依赖被一并打进函数
首次冷启动过慢
图片生成、远程抓取、聚合请求超时

而这个项目里本身就有：

OG 图生成
第三方 API 代理
聚合数据请求
多语言中间件

所以如果你在云函数平台继续叠加更多逻辑，要特别关注：

函数体积
最大执行时长
区域设置
冷启动

21.8.10 Middleware / 地理位置能力在不同平台表现不一样

这个项目的请求代理逻辑使用了：

@vercel/functions 的 geolocation
@vercel/functions 的 ipAddress

同时又兼容读取：

cf-ipcountry
cf-ipcity
cf-iplatitude
cf-iplongitude

也就是说：

在 Vercel 上，它会优先走 Vercel 的请求上下文
在 Cloudflare 一类平台上，可能走 cf-* 头
在其他平台上，这些值可能为空

因此你不能把：

地理位置
请求来源 IP

当作绝对可靠的部署前提，只能把它当作增强信息。

21.8.11 Webhook 地址指向了 Preview 域名或旧域名

很多人把前端上到云函数平台后，会出现：

页面能打开
后端内容更新后前端不刷新
文章重新发布后首页还是旧数据

通常原因不是“缓存坏了”，而是：

后端发 webhook 的地址还是旧域名
或者发到了 Preview 域名
或者 WEBHOOK_SECRET 前后不一致

正确做法：

后端 webhook 始终指向生产前端地址：

TEXT

https://<YOUR_FRONTEND_DOMAIN>/api/webhook

CodeBlock Loading...

生产环境前后端共享同一个 WEBHOOK_SECRET

21.8.12 第三方代理接口缺少密钥，线上才报 500

本项目前端内部还带了几个代理路由，常见包括：

GitHub 代理
TMDB 代理
Bangumi 代理

其中：

GH_TOKEN
TMDB_API_KEY

如果在云函数平台没配，最典型的结果就是：

本地可用
线上对应模块 500
某些页面局部报错但首页不一定全挂

所以部署后要主动检查这些功能点，而不是只看首页能不能打开。

21.8.13 推荐的云函数部署结论

如果你后面还想继续走云函数方案，建议直接记住下面这个结论：

前端可以部署到云函数平台
后端不要按纯云函数思路部署
API_URL 在云函数里必须是可访问的绝对地址
NEXT_PUBLIC_* 改完后要重新部署
NEXT_PUBLIC_GATEWAY_URL 必须指向真正的后端网关域名
WEBHOOK_SECRET、TMDB_API_KEY、GH_TOKEN 必须按环境完整配置
Preview / Production 的变量不能混

如果你只想要稳定省心，不想再被云函数配置反复折腾：

前端：可上云函数
后端：用 Docker 常驻部署

这就是这个项目最稳的组合。

22. 安全与隐私建议

22.1 不要提交这些内容

GH_TOKEN
TMDB_API_KEY
WEBHOOK_SECRET
JWT_SECRET
ENCRYPT_KEY
服务器 IP
个人域名
个人邮箱
Docker Hub 私有命名规则

22.2 环境变量文件权限

BASH

chmod 600 /opt/yohaku-env/yohaku.env
chmod 600 /opt/mx-space/.env

CodeBlock Loading...

22.3 Token 权限最小化

GH_PAT 只给源码读取权限
DOCKERHUB_TOKEN 只用于推镜像
第三方 API Key 不要复用管理员密钥

22.4 敏感信息分层

公开地址 -> build args
密钥 -> 服务器 env
数据库 -> 后端容器 env
反向代理 -> 站点配置，不写业务密钥

23. 推荐的最终部署方案

如果你要一个最稳、后续最好维护的方案，我建议：

后端 mx-core + mongo + redis 同机 Docker 部署
前端 yohaku-web 走 Docker Hub 镜像部署
前端和后端在同一个 Docker 网络
前端 API_URL=http://mx-core:2333/api/v2
浏览器侧始终走 https://<YOUR_API_DOMAIN>/api/v2
OpenResty / Nginx 只负责反向代理和 HTTPS
前端更新只重新构建镜像，不在服务器编译

这是当前仓库最适合的使用方式。

24. 最小可用上线清单

如果你只想快速上线，最少做这些事：

24.1 准备后端

BASH

cd /opt/mx-space
docker compose up -d
curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

24.2 准备前端环境变量

BASH

cat > /opt/yohaku-env/yohaku.env <<'EOF'
NODE_ENV=production
HOSTNAME=0.0.0.0
PORT=2323
NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>
API_URL=http://mx-core:2333/api/v2
WEBHOOK_SECRET=<GENERATE_A_STRONG_SECRET>
TMDB_API_KEY=<YOUR_TMDB_API_KEY>
GH_TOKEN=<YOUR_GITHUB_TOKEN>
EOF

CodeBlock Loading...

24.3 拉前端镜像并启动

BASH

cd /opt/yohaku
docker compose pull
docker compose up -d

CodeBlock Loading...

24.4 配反代

<YOUR_FRONTEND_DOMAIN> -> 127.0.0.1:2323
<YOUR_API_DOMAIN> -> 127.0.0.1:2333

24.5 验证

BASH

curl http://127.0.0.1:2323/api/healthz
curl http://127.0.0.1:2333/api/v2/ping

CodeBlock Loading...

25. 维护与更新流程

25.1 更新前端

BASH

# 在 GitHub 重新触发 Actions 构建镜像

cd /opt/yohaku
docker compose pull
docker compose up -d

CodeBlock Loading...

25.2 更新后端

BASH

cd /opt/mx-space
docker compose pull
docker compose up -d

CodeBlock Loading...

25.3 查看运行状态

BASH

docker compose ps
docker stats

CodeBlock Loading...

26. 最后说明

这份 Wiki 已经尽量覆盖：

当前部署仓库的真实用途
前端源码结构与本地开发
后端兼容栈的启动方式
前后端对接关系
Docker 化部署
GitHub Actions 自动构建
OpenResty / Nginx 反代
可直接复制的环境变量与配置模板
安全与隐私处理方式

如果你继续沿用这份文档，建议你保持一个原则：

所有公开文档只保留占位符，所有真实值只进服务器环境变量。

27. 官方链接索引（按场景分类）

为了方便你后续继续扩写这份 Wiki，这里再给一个集中索引版本。

27.1 源项目主页

Yohaku 公共项目页：https://github.com/Innei/Yohaku
MX Space Core：https://github.com/mx-space/core

27.2 前端开发

Next.js：https://nextjs.org/docs
React：https://react.dev/
pnpm：https://pnpm.io/installation
Turborepo：https://turborepo.dev/repo/docs
Tailwind CSS：https://tailwindcss.com/docs/installation
TypeScript：https://www.typescriptlang.org/docs/

27.3 后端与数据层

MX Space Core：https://github.com/mx-space/core
MongoDB：https://www.mongodb.com/docs/
Redis：https://redis.io/docs/latest/
Socket.IO：https://socket.io/docs/v4/
Better Auth：https://better-auth.com/docs/introduction

27.4 部署与运维

Docker：https://docs.docker.com/
Docker Hub：https://docs.docker.com/docker-hub/
GitHub Actions：https://docs.github.com/actions
OpenResty：https://openresty.org/en/
Nginx：https://nginx.org/en/docs/

27.5 第三方能力

TMDB 开发者文档：https://developer.themoviedb.org/v3/reference/intro/getting-started
Git LFS：https://git-lfs.com/

27.6 云函数 / Serverless 参考

Vercel Functions：https://vercel.com/docs/functions/
Vercel Limits：https://vercel.com/docs/limits/overview
Vercel 环境变量：https://vercel.com/docs/environment-variables
Vercel Edge Runtime：https://vercel.com/docs/concepts/functions/edge-functions/edge-runtime
Next.js 环境变量：https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables
Next.js Route Segment Config：https://nextjs.org/docs/15/app/api-reference/file-conventions/route-segment-config
Next.js Edge Runtime：https://nextjs.org/docs/pages/building-your-application/rendering/edge-and-nodejs-runtimes

28. 云函数 / Serverless 部署专项补充

这一节是给“曾经在云函数配置上反复出错”的情况单独准备的，你可以把它理解成部署前的强制核对清单。

28.1 什么时候适合上云函数

适合：

只部署前端
页面以 SSR / RSC / Route Handler 为主
后端已经在别处稳定运行
你接受 Preview / Production 多环境管理

不适合：

想把整个后端也一起塞进云函数
想在云函数里跑稳定 WebSocket 服务端
想依赖 Docker 内网地址互通
想“改个环境变量立刻生效但不重新部署”

28.2 云函数部署时必须满足的前提

前端必须能访问真实后端

ENV

NEXT_PUBLIC_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_CLIENT_API_URL=https://<YOUR_API_DOMAIN>/api/v2
NEXT_PUBLIC_GATEWAY_URL=https://<YOUR_API_DOMAIN>
API_URL=https://<YOUR_API_DOMAIN>/api/v2

CodeBlock Loading...

绝对不要在云函数里保留这些 Docker 写法

ENV

API_URL=http://mx-core:2333/api/v2
API_URL=http://host.docker.internal:2333/api/v2
API_URL=http://172.17.0.1:2333/api/v2

CodeBlock Loading...

28.3 云函数部署前的环境变量核对清单

生产环境至少确认：

NEXT_PUBLIC_API_URL
NEXT_PUBLIC_CLIENT_API_URL
NEXT_PUBLIC_GATEWAY_URL
API_URL
WEBHOOK_SECRET
TMDB_API_KEY
GH_TOKEN

如果是 Vercel 这类平台，再额外确认：

这些变量是否同时配置到了正确环境
是不是只配了 Preview 没配 Production
改完后是否重新触发了一次 Deployment

28.4 云函数版本的最小可用思路

推荐拓扑：

前端部署到云函数平台
后端继续放在容器 / 服务器
前端所有 API 和 WebSocket 都走后端公网域名
Webhook 从后端回调前端生产域名

28.5 如果你后续还要继续扩写 Wiki

建议你单独维护一个“云函数部署实录”附录，专门记录：

你实际使用的平台
哪些环境变量配错过
哪个报错最后对应哪一项配置
Preview 和 Production 的差异
Webhook / WebSocket / Edge Runtime 的特殊坑

这样后续每次迁移平台时，就不用再从头踩一次。

Yohaku 项目完整 Wiki

Yohaku 项目完整 Wiki

Yohaku 项目完整 Wiki

0. 官方链接与源项目入口

0.1 核心源项目入口

0.2 关键技术栈官方文档

0.3 建议阅读顺序

1. 这份仓库是什么

2. 项目总体架构

2.1 逻辑拓扑

2.2 端口约定

2.3 当前方案的关键思想

3. 前后端职责划分

3.1 前端（Yohaku）

3.2 后端（MX Space Core / 兼容实现）

4. 目录说明

4.1 当前部署仓库

4.2 前端上游源码仓库（逻辑结构）

4.3 后端兼容仓库（逻辑结构）

5. 你需要先准备什么

5.1 本地开发机

5.2 服务器

6. 域名、路径、镜像命名建议

7. 环境变量总表

7.1 前端公开构建变量

7.2 前端运行时变量

7.3 后端核心变量

7.4 建议的密钥生成命令

8. 前端本地开发搭建

8.1 拉取前端源码

8.2 启用 pnpm

8.3 安装依赖

8.4 配置前端本地环境变量

8.5 启动前端

8.6 本地前端构建

8.7 前端开发阶段可参考的官方链接

9. 后端本地 / 服务器搭建

9.1 方式 A：从源码启动后端

9.2 方式 B：用 Docker 直接部署后端

9.3 后端搭建阶段可参考的官方链接

10. 前端对后端的接口约定

10.1 浏览器请求 API

10.2 前端 SSR 请求 API

10.3 WebSocket 地址

10.4 Auth 地址

10.5 Webhook 地址

11. 当前仓库的前端镜像构建方式

11.1 Dockerfile.hub 的作用

11.2 建议保留的 Dockerfile.hub

11.3 镜像构建相关官方文档

12. GitHub Actions 自动构建镜像

12.1 需要的 GitHub Secrets

12.2 推荐的工作流文件

12.3 首次触发

12.4 GitHub Actions 相关官方文档

13. 前端生产环境变量文件

13.1 如果后端不在同一个 Docker 网络

14. 前端服务器部署（只部署前端）

14.1 /opt/yohaku/docker-compose.yml

14.2 启动命令

15. 一体化部署（前后端同机同网）

15.1 组合部署时前端 env 要这样写

15.2 启动组合部署

16. OpenResty / Nginx 反向代理

16.1 前端站点配置

16.2 后端站点配置（含 WebSocket）

16.3 HTTPS

16.4 反向代理与网关参考链接

17. 本地手工构建并推送前端镜像

18. 服务器上线顺序

18.1 先起后端

18.2 再起前端

18.3 最后接入反向代理

19. 上线后检查清单

19.1 检查前端容器

19.2 检查后端容器

19.3 检查前端健康接口

19.4 检查后端健康接口

19.5 检查前端容器内是否能访问后端

19.6 浏览器检查

11.1 `Dockerfile.hub` 的作用

11.2 建议保留的 `Dockerfile.hub`

14.1 `/opt/yohaku/docker-compose.yml`

21.4 `host.docker.internal` 不通

21.5 构建时报 `git-lfs` 相关错误

21.6 `pnpm install --frozen-lockfile` 失败

21.8.3 把 `API_URL` 写成相对路径，导致服务端请求报错

21.8.6 把 `NEXT_PUBLIC_GATEWAY_URL` 配成前端域名