安和鱼文档

Anheyu 提供了强大的主题定制功能，支持完全自定义前端界面，让您可以创建独特的视觉体验和用户交互。

工作原理

默认：主站前台为 Next.js（output: 'standalone'），由 Go 进程拉起 Node 运行 frontend/.next/standalone，页面经 8091 反向代理访问（详见 internal/frontend）。
可选：若可执行文件旁存在符合检测条件的 static/ 目录（含有效 index.html），公开页可走纯静态 HTML；/admin、/login 等仍由 Next 处理。与「改 Next 子模块再构建」是两条路径。

自定义前端的优势

🎨 完全控制界面设计和用户体验
🚀 支持服务端渲染（SSR），提升 SEO 效果
🔧 可以添加自定义功能和组件
📱 响应式设计，适配各种设备
⚡ 基于 Next.js + React + TypeScript，开发体验优秀

前置要求

在开始自定义主题之前，请确保您的开发环境已安装：

Node.js >= 18.0 (安装指南)
pnpm >= 10.0 (安装指南)
Git (安装指南)

步骤 1：获取前端源码

从 GitHub 克隆主应用仓库并进入前端目录。frontend 为 Git 子模块（Next.js 源码独立仓库），必须使用 --recurse-submodules 一并拉取，否则 frontend 目录为空。

# --recurse-submodules：递归克隆子模块（等同于旧版写法 git clone --recursive）
git clone --recurse-submodules https://github.com/anzhiyu-c/anheyu-app.git
cd anheyu-app/frontend

若已克隆过主仓库但 frontend 为空

在仓库根目录执行：

git submodule update --init --recursive

然后再 cd frontend。

步骤 2：安装依赖

使用 pnpm 安装项目依赖：

# 安装依赖
pnpm install

为什么使用 pnpm？

pnpm 相比 npm/yarn 具有更快的安装速度、更少的磁盘占用，并且与项目的开发环境保持一致。

步骤 3：开发环境运行

在开发过程中，您可以启动本地开发服务器进行实时预览：

# 启动开发服务器
pnpm run dev

开发服务器启动后，默认在 http://localhost:3000 提供预览服务（与 package.json 中 next dev 一致）。

开发环境注意事项

开发环境需要连接到运行中的 Anheyu 后端服务（通常是 http://localhost:8091），确保后端服务正常运行。若需指向已部署的后端，可在本地通过环境变量或 next.config 中的代理目标（如 BACKEND_URL）调整后端地址，保持与当前 Next 工程约定一致。

步骤 4：自定义修改

现在您可以根据需求修改前端代码：

主要目录结构

⚙️next.config.ts

📦package.json

目录说明：

src/app/ - Next.js App Router：布局、页面与路由（page.tsx、layout.tsx 等）
src/components/ - 可复用 React 组件
src/lib/ - 工具函数、API 客户端、配置等
src/styles/ - 全局样式（如 Tailwind 入口）
public/ - 公共静态文件
next.config.ts - Next.js 配置（含开发代理等）
package.json - 依赖与脚本（next dev / next build）

常见自定义场景

修改主题颜色方案

编辑全局样式或 Tailwind 主题配置（以项目内实际路径为准，如 src/styles/、tailwind.config 等）
修改 CSS 变量，如：

:root {
  --anzhiyu-theme: #163bf2;
  --anzhiyu-theme-op: #4259ef23;
  --anzhiyu-theme-op-deep: #4259efdd;
  --anzhiyu-theme-op-light: #4259ef0d;
}

若使用 Tailwind CSS，编辑对应的全局 CSS 与 tailwind 配置

调整页面布局

修改 src/app/ 下的布局（如 layout.tsx）与路由分组
编辑各路由目录中的 page.tsx 及共用布局组件
调整响应式设计和网格布局

自定义UI组件

在 src/components/ 中修改现有组件
创建新的自定义组件
更新组件的样式和交互逻辑

添加新功能模块

在 src/app/ 下按 App Router 约定新增路由目录与 page.tsx
按需补充 layout.tsx、加载与错误边界等
创建对应的 API 调用和数据处理

步骤 5：构建生产版本

完成自定义修改后，构建生产版本：

# 构建生产版本
pnpm run build

构建完成后，在 frontend/ 下生成 Next standalone 产物：.next/standalone/、.next/static/，并与 public/ 一并供运行时使用（与 frontend/next.config.ts 中 output: 'standalone' 一致）。

步骤 6：部署自定义前端

根据您使用的部署方式，部署自定义前端的步骤会有所不同：

Docker Compose 部署方式

A. 自定义 Next.js 前台（默认路径）

克隆主仓库（含 frontend 子模块），在仓库根目录修改子模块并完成构建：

cd /path/to/anheyu-app
make frontend-build

按主仓库 Dockerfile / Makefile 重新构建镜像并启动 Compose（镜像内会包含 frontend/.next/standalone、frontend/.next/static 与 public/，与官方构建一致）。

B. 可选：挂载 static/ 纯静态站

若仅需 static 目录模式（带有效 index.html 的静态资源，公开页由 Go 直出），在宿主机准备目录并挂载：

mkdir -p ~/anheyu/static
# 将静态 HTML 站点放入 static/

services:
  anheyu:
    volumes:
      - ./data:/anheyu/data
      - ./static:/anheyu/static

说明

与 Next 替换 是两条路径：不要期望把 pnpm run build 的 standalone 产物「当作 dist」拷进 static/。

Docker 单容器部署方式

自定义 Next：在本地完成 make frontend-build 后按主仓库文档 docker build 打出包含 frontend/.next/standalone 的镜像，再 docker run；或使用官方镜像 + ANHEYU_FRONTEND_URL 指向外部 Next。

可选 static 挂载：若启用 static 模式，准备带 index.html 的目录并挂载：

mkdir -p ~/anheyu/static
docker run -d \
  --name anheyu-app \
  -p 8091:8091 \
  -v ~/anheyu/data:/anheyu/data \
  -v ~/anheyu/static:/anheyu/static \
  anheyu/anheyu-backend:latest

权限

确保 static 目录权限可被容器内进程读取。

源码部署方式

自定义 Next（推荐）：在仓库根目录执行 make frontend-build，再编译后端；运行目录中需保留完整的 frontend/（含 .next/standalone 等），与 internal/frontend 启动逻辑一致。

cd /path/to/anheyu-app
make frontend-build
go build -ldflags="-s -w" -o anheyu-app .
./anheyu-app

可选：static 纯静态站：在可执行文件旁放置带 index.html 的 static/，用于公开页静态模式（见上文 Callout）。

说明

当前主路径为 Next standalone，不再使用旧文档中的 frontend/dist 或向 assets/dist 拷贝 SPA 产物的方式。

二进制文件部署方式

Next 前台：将发布包中的 frontend/ 目录与二进制放在同一部署目录（或设置 ANHEYU_FRONTEND_DIR），其中需包含 frontend/.next/standalone（由 make frontend-build 生成）。Go 会启动 Node 运行 server.js。

cd ~/anheyu
# 目录中应有：anheyu、frontend/.next/standalone/...
./anheyu

可选 static/：若使用静态站模式，再放置带 index.html 的 static/（与二进制同目录或通过 ANHEYU_STATIC_DIR 指定）。

说明

默认前台为 Next standalone，不是必须把资源放进 static/；static/ 仅在选择该模式时生效。

步骤 7：重启应用

根据您的部署方式，使用对应的重启命令：

重启 Docker Compose 服务

# 进入 docker-compose.yml 所在目录
cd ~/anheyu

# 停止服务
docker compose down

# 重新启动服务
docker compose up -d

# 或者直接重启
docker compose restart anheyu

查看日志确认

docker compose logs -f anheyu

说明

默认应看到 Next 前端相关日志；仅在使用 static 模式且满足检测条件时才会出现「外部 static 目录」类提示。

重启 Docker 容器

# 停止并删除现有容器
docker stop anheyu-app
docker rm anheyu-app

# 按需添加 static 挂载（仅在使用 static 模式时）
docker run -d \
  --name anheyu-app \
  -p 8091:8091 \
  -v ~/anheyu/data:/anheyu/data \
  -v ~/anheyu/static:/anheyu/static \
  anheyu/anheyu-backend:latest

查看容器日志

docker logs -f anheyu-app

Docker 重启注意

重新创建容器时，确保所有必需的挂载卷都已正确配置。

重启源码部署的应用

如果是前台运行：

# 按 Ctrl+C 停止当前应用，然后重新启动
./anheyu-app

如果是后台运行：

# 查找并停止进程
pkill anheyu-app

# 或者使用具体的进程ID
ps aux | grep anheyu-app
kill <进程ID>

# 重新启动
nohup ./anheyu-app > anheyu.log 2>&1 &

如果使用 systemd 服务：

sudo systemctl restart anheyu
sudo systemctl status anheyu

查看启动日志

# 查看日志文件
tail -f anheyu.log

# 或查看 systemd 日志
sudo journalctl -u anheyu -f

源码部署重启说明

修改 Next 后需已执行 make frontend-build 再重启；仅 static 模式时替换 static/ 后重启即可。

重启二进制文件应用

如果是前台运行：

# 按 Ctrl+C 停止应用，然后重新启动
./anheyu

如果是后台运行：

# 停止应用
pkill anheyu

# 重新启动
nohup ./anheyu > ./data/anheyu.log 2>&1 &

# 查看进程状态
ps aux | grep anheyu

如果使用 systemd 服务：

# 重启服务
sudo systemctl restart anheyu

# 查看服务状态
sudo systemctl status anheyu

# 查看服务日志
sudo journalctl -u anheyu -f

验证启动

tail -f ./data/anheyu.log

二进制部署重启

更新 Next 时确保 frontend/（standalone）已同步；static 模式在检测到有效 static/index.html 时才会切换公开页路由。

验证自定义前端生效

默认（Next）：日志中应有 Next.js 反向代理 / 内置前端启动 等提示（见主程序输出）；访问 http://localhost:8091 打开站点。
仅当启用 static 模式时：若存在有效 static/index.html，可能看到 「正在使用 [模式一]: 外部 'static' 目录」；公开页走静态目录，后台仍走 Next。

快速参考

为了方便查阅，以下是各种部署方式的自定义前端要点总结：

当前架构（与仓库实现一致）

构建产物：frontend 使用 Next.js output: 'standalone'，pnpm run build / npm run build 后在 frontend/ 下生成 .next/standalone/（含 server.js）、.next/static/ 与 public/，没有旧版 SPA 的 dist/ 目录。
默认运行：Go 启动内嵌 Node 进程运行 standalone（默认端口 3000），对外只暴露 8091，由中间件将页面请求转发到 Next（详见主仓库 internal/frontend、Dockerfile）。
自定义主站（Next）：修改子模块代码后执行 make frontend-build（或 cd frontend && npm ci && npm run build），再重新构建镜像或部署时保证运行环境里的 frontend/ 目录与镜像中 COPY 结构一致；也可设置 ANHEYU_FRONTEND_URL 指向已单独部署的 Next 服务，ANHEYU_FRONTEND_DIR 可覆盖前端目录路径（默认 ./frontend）。
static/ 目录（可选）：若存在带有效 index.html 的 static/，公开页可走该静态目录（类 SPA）；/admin、/login、/_next/ 仍由 Next 处理。适用于纯静态 HTML 资源，不要把 standalone 的 .next 整包误拷成「静态站」；与 Next 替换是两条路径。

Docker Compose 快速参考

git clone --recurse-submodules https://github.com/anzhiyu-c/anheyu-app.git
cd anheyu-app
make frontend-build
# 按主仓库 Makefile / Dockerfile 构建镜像并 docker compose up

可选：启用 static 模式时再挂载 ./static:/anheyu/static（需有效 index.html）。

Docker 单容器快速参考

# 自定义 Next：本地 make frontend-build 后 docker build，或使用 ANHEYU_FRONTEND_URL
# 可选 static 挂载：
mkdir -p ~/anheyu/static
docker run -d --name anheyu-app -p 8091:8091 \
  -v ~/anheyu/data:/anheyu/data \
  -v ~/anheyu/static:/anheyu/static \
  anheyu/anheyu-backend:latest

源码部署快速参考

cd /path/to/anheyu-app
make frontend-build
go build -ldflags="-s -w" -o anheyu-app .
./anheyu-app

可选：使用 static 模式时，在可执行文件旁准备 static/index.html。

二进制文件快速参考

# 发布包中需包含与二进制同级的 frontend/（含 .next/standalone）
cd ~/anheyu
./anheyu

可选：ANHEYU_FRONTEND_DIR、ANHEYU_STATIC_DIR、ANHEYU_FRONTEND_URL 见主仓库与上文 Callout。

选择建议

部署方式	自定义前端难度	推荐指数	适用场景
Docker Compose	⭐⭐	⭐⭐⭐⭐⭐	生产环境，完整服务栈
Docker	⭐⭐⭐	⭐⭐⭐⭐	灵活的容器化部署
源码部署	⭐⭐⭐⭐	⭐⭐⭐	开发环境，需要二次开发
二进制文件	⭐	⭐⭐⭐⭐⭐	生产环境，追求性能

推荐流程

新手用户：选择 Docker Compose，一键部署完整功能
进阶用户：选择 Docker Compose，如果喜欢折腾的话，那就选二进制获得最佳性能和复杂环境操作，可能会没有售后
开发者：选择源码部署，便于调试和二次开发
运维人员：选择 Docker，灵活的容器化管理

高级定制

自定义构建与代理

编辑 next.config.ts 以自定义构建行为、开发与生产环境下的 API 代理（例如将 /api 转发到 Go 后端）：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
  // async rewrites() { ... }  // 与后端地址、Docker 内网等相关
};

export default nextConfig;

具体字段以仓库内 frontend/next.config.ts 为准。

最佳实践

开发时的最佳实践

版本控制：使用 Git 管理您的自定义代码
组件化开发：保持组件的单一职责和可重用性
样式组织：合理组织 CSS/SCSS 文件结构
TypeScript：利用 TypeScript 提供的类型安全
代码规范：遵循项目的 ESLint 和 Prettier 配置

性能优化建议

懒加载：对非首屏组件实施懒加载
资源优化：压缩图片，优化静态资源大小
缓存策略：合理配置浏览器缓存
代码分割：利用 Next.js 与动态 import() 做路由级与组件级分割
打包分析：使用 @next/bundle-analyzer 等工具分析构建产物体积

维护和更新

定期更新：关注上游仓库的更新，及时合并新功能
备份配置：备份您的自定义配置和重要修改
测试环境：在生产环境部署前先在测试环境验证
文档记录：记录重要的自定义修改和配置
版本标记：为您的自定义版本打上版本标签

故障排除

常见问题及解决方案

调试技巧

查看启动日志：确认 Next 是否启动、static 模式是否命中（见上文）。
浏览器开发工具：检查网络请求与控制台错误。
对比构建产物：frontend/.next/standalone 是否与部署环境一致。
逐步调试：先按主仓库默认流程 make frontend-build 能跑通，再叠加自定义。

完成自定义

恭喜！您已经成功掌握了 Anheyu 的主题定制功能。现在您可以创建独特的界面设计，为用户提供个性化的体验。记得定期备份您的自定义代码，并关注官方更新以获得最新功能。

📚 官方文档：参考完整的开发文档和 API 说明
💬 社区讨论：在 GitHub Issues 中参与讨论和提问
🎨 主题分享：与社区分享您的自定义主题
🐛 问题反馈：报告 Bug 或提出功能建议

通过自定义前端，您可以让 Anheyu 完全符合您的品牌形象和用户需求。开始您的创意之旅吧！

自定义前端