# note-wall

**Repository Path**: Sonve/note-wall

## Basic Information

- **Project Name**: note-wall
- **Description**: 便签墙
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SV-Nuxt

## 项目概述

本项目为基于 `Nuxt 4` 的全栈应用模板，面向「管理后台 + 前台页面」场景，内置 Element Plus、Pinia、Prisma、PostgreSQL、Redis、UnoCSS、PM2 和 Docker Compose 等常用工程配置。

## 目录结构

更多 Nuxt 标准目录说明可参考 [Nuxt Directory Structure](https://nuxt.com/docs/4.x/directory-structure)。本项目主要目录和文件如下：

```text
app/                    # Nuxt 前端应用目录，包含页面、组件、API 封装、类型和工具方法
server/                 # Nuxt Nitro 服务端目录，包含后端接口、服务端工具和服务端类型
prisma/                 # Prisma schema、种子脚本和生成产物目录
public/                 # 静态资源目录
docs/                   # 项目计划、任务和阶段性文档
nuxt.config.ts          # Nuxt 配置
uno.config.ts           # UnoCSS 配置
prisma.config.ts        # Prisma CLI 配置
ecosystem.config.cjs    # PM2 部署配置
Dockerfile              # Docker 镜像构建配置
docker-compose.yml      # Docker Compose 编排配置
```

## 技术栈选型

当前项目面向「管理后台 + 前台页面」场景，优先选择开发效率高、与 Nuxt 生态契合度高的方案：

> 优先从 [Nuxt Modules](https://nuxt.com/modules) 中获取方案

- 前端框架：`Nuxt 4`
- UI 组件库：`element-plus` + `@element-plus/nuxt`
- 状态管理：`pinia` + `@pinia/nuxt`
- 状态持久化：`pinia-plugin-persistedstate`
- 数据库：`PostgreSQL 18` + `Redis`
- ORM：`Prisma ORM 7`
- Nuxt 数据层接入：优先遵循 Prisma 官方 Nuxt 指南，`@prisma/nuxt` 仅作为可选辅助模块评估
- 样式方案：`UnoCSS` + `Sass`
- 常用工具库：`@vueuse/core`、`dayjs`、`lodash-es`
- 图标方案：优先使用 `iconfont`，其次 `@element-plus/icons-vue`，需要原子图标时可通过 `UnoCSS presetIcons` 扩展

### 环境变量

- [.env](https://nuxt.com/docs/4.x/directory-structure/env) 环境变量文档说明
- Nuxt 内置 `dotenv` 机制，开发和构建阶段会读取根目录的 `.env`
- 默认框架中只保留 `.env.example` 作为示例；开发或构建时可复制为 `.env`
- `.env.example` 不用被 `.gitignore` 忽略；但 `.env` 必须被 `.gitignore` 忽略，不能提交到仓库，防止信息泄露
- 部分环境变量可搭配 `nuxt.config.ts` 中 [runtimeConfig](https://nuxt.com/docs/4.x/api/nuxt-config#runtimeconfig-1) 使用，生产环境应通过宿主环境注入，或按需显式加载
- `.env.example` 同时覆盖本地开发、PM2 和 Docker Compose，配置时请仔细参考环境变量注释

## 项目启动

### 环境要求

- `Node.js 24`
- `pnpm`
- 本地开发需要可访问的 `PostgreSQL 18` 和 `Redis`，也可以通过 Docker Compose 启动内置服务
- PM2 部署需要服务器已安装 `PM2`
- Docker Compose 部署需要服务器已安装 `Docker` 和 `Docker Compose`

### 开发环境

首次启动前安装依赖：

```bash
pnpm install
```

复制环境变量示例文件，并按本地环境修改数据库连接等配置：

```bash
cp .env.example .env
# 或者直接手动复制文件
```

初始化数据库结构并生成 Prisma Client：

```bash
# 项目初始化、schema.prisma 变动时需要先运行 push
pnpm prisma:push
# schema.prisma 变动时运行 generate
pnpm prisma:generate
# 若需预加载数据库种子数据，则执行：
pnpm prisma:seed
```

启动 Nuxt 开发服务：

```bash
pnpm dev
```

本地仿生产环境预览需要先完成构建：

```bash
pnpm build
pnpm preview
```

常用检查命令：

```bash
pnpm typecheck
pnpm build
```

### 生产环境

生产环境需要先完成依赖安装、环境变量配置、数据库结构同步、Prisma Client 生成和 Nuxt 构建：

```bash
pnpm install

# 已维护 prisma migrations 时，优先使用：
# pnpm prisma:migrate:deploy
# 当前模板初始化或未维护 migrations 时，可使用：
pnpm prisma:push
# schema.prisma 变动时运行 generate
pnpm prisma:generate
# 若需预加载数据库种子数据，则执行：
pnpm prisma:seed

pnpm build
```

> 生产环境建议优先通过 Prisma migrations 管理数据库结构变更。`pnpm prisma:push` 更适合模板初始化、开发环境或受控的一次性部署操作。

构建产物会输出到 `.output/` 目录。Node.js 服务入口为：

```bash
.output/server/index.mjs
```

> 在使用 `PM2` 部署时，生产环境变量依赖 `ecosystem.config.cjs` 自动注入 `.env`，所以需要选择 `ecosystem.config.cjs` 为启动文件

## 项目部署

### 项目文件上传

基础文件：

```text
app/
prisma/
public/
server/
docs/
.env.example
nuxt.config.ts
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
prisma.config.ts
README.md
tsconfig.json
uno.config.ts
```

- 以下文件或目录不需要上传，应在服务器上重新生成或单独配置：

```text
.nuxt/
.output/
node_modules/
prisma/generated/
.env
.gitignore
```

- 上传后务必配置好 `.env` 环境变量

```bash
cp .env.example .env
```

> 若直接上传了完整的 `prisma/` 目录，别忘了删掉 `prisma/generated/` 文件夹，再使用 `pnpm prisma:generate` 重新构建

### 宝塔面板 PM2 部署

宝塔面板中可使用 `PM2` 管理 `Nuxt` 的 `Node` 项目，推荐部署流程：

#### 1. 文件上传

先创建项目目录，进行 [项目文件上传](#项目文件上传)

```bash
# PM2 部署必须上传
ecosystem.config.cjs

# 可忽略 Docker Compose 配置文件
Dockerfile
docker-compose.yml
.dockerignore
```

#### 2. 项目构建

编辑生产环境变量 `.env` 后，再运行：

```bash
pnpm install

# 已维护 prisma migrations 时，优先使用：
# pnpm prisma:migrate:deploy
# 当前模板初始化或未维护 migrations 时，可使用：
pnpm prisma:push
# schema.prisma 变动时运行 generate
pnpm prisma:generate

pnpm build

# 若需预加载数据库种子数据，则执行：
pnpm prisma:seed
```

#### 3. 创建 PM2 项目

宝塔面板中选择添加 `Node` 项目，选择 `PM2` 项目，启动文件选择 `ecosystem.config.cjs`，其他配置项全默认即可

> 生产环境变量建议维护在服务器项目根目录的 `.env`，环境配置文件 `ecosystem.config.cjs` 会读取并映射 `.env`。

#### 4. 外网映射

开启 `外网映射`，配置域名，配置 `SSL` 证书

#### 5. 端口放行

云服务器和宝塔面板的防火墙端口记得放行

### Docker Compose 部署（推荐）

#### 1. 文件上传

先创建项目目录，进行 [项目文件上传](#项目文件上传)

```bash
# Docker Compose 部署必须上传
Dockerfile
docker-compose.yml
.dockerignore

# 可忽略 PM2 配置文件
ecosystem.config.cjs
```

Docker Compose 配置会启动三个服务：

- `app`：等待 PostgreSQL 和 Redis 健康后，先执行 `pnpm prisma:push` 和 `pnpm prisma:seed` 初始化数据库结构和种子数据，再运行 Nuxt Nitro 生产产物，入口为 `.output/server/index.mjs`
- `postgres`：提供 PostgreSQL 数据库，并使用 `postgres-data` volume 持久化数据
- `redis`：提供 Redis 缓存服务，并使用 `redis-data` volume 持久化数据

#### 2. 启动服务

先编辑生产环境变量 `.env`。

Docker Compose 会默认读取根目录 `.env`，用于变量插值，并将 `docker-compose.yml` 中声明的环境变量注入容器：

```bash
docker compose up -d --build
```

查看容器状态和日志：

```bash
docker compose ps
docker compose logs -f app
```

访问服务：

```text
http://服务器IP或者域名:13060/
```

如果修改了 `NUXT_PORT`，对外访问端口也会随之变化。`app` 容器内部会将 `NUXT_HOST` / `NUXT_PORT` 映射为 Nitro 运行所需的 `HOST` / `PORT`。

#### 3. 停止服务：

```bash
docker compose down
```

如果需要同时删除 PostgreSQL 和 Redis 数据卷：

```bash
docker compose down -v
```

> `down -v` 会删除 PostgreSQL 和 Redis 持久化数据，只应在确认不再需要当前数据时执行。
>
> 本项目使用 `postgres:18-alpine`。PostgreSQL 18+ 镜像的数据卷挂载在 `/var/lib/postgresql`，不要改回旧版本常见的 `/var/lib/postgresql/data`，否则容器可能因为数据目录格式不兼容而启动失败。

#### 4. 重新构建发布

代码更新后，在服务器项目根目录执行：

```bash
docker compose up -d --build
```

当前 Docker Compose 模板会在 `app` 容器启动前自动执行 `pnpm prisma:push` 和 `pnpm prisma:seed`。当项目开始维护正式 Prisma migrations 后，建议将 `app` 的启动命令调整为 `pnpm prisma:migrate:deploy && pnpm prisma:seed && node .output/server/index.mjs`，或改由 CI/CD 执行受控迁移。

## 上传文件静态访问配置

媒体库或文件上传接口返回的公开资源地址通常是以 `/uploads/` 开头的站点相对路径，例如：

```text
/uploads/public/image/2026/06/xxx.png
```

该路径不是服务器磁盘路径，而是浏览器访问 URL。生产环境需要让 Nginx、宝塔面板或其他静态文件服务把 `/uploads/` 映射到真实上传目录，否则公开资源 URL 会无法访问。

### Docker Compose 部署

Docker Compose 默认会把宿主机上传目录挂载到容器内 `/app/uploads`：

```yaml
volumes:
  - ${NUXT_UPLOAD_HOST_DIR:-/www/sv-nuxt/uploads}:/app/uploads
```

此时建议保持环境变量：

```dotenv
NUXT_UPLOAD_DIR=/app/uploads
NUXT_PUBLIC_UPLOAD_BASE=/uploads
NUXT_UPLOAD_HOST_DIR=/www/sv-nuxt/uploads
```

然后在 Nginx 或宝塔站点配置中增加静态映射：

```nginx
location /uploads/ {
    alias /www/sv-nuxt/uploads/;
    access_log off;
    expires 30d;
}
```

配置后，浏览器访问：

```text
https://你的域名/uploads/public/image/2026/06/xxx.png
```

实际会读取宿主机文件：

```text
/www/sv-nuxt/uploads/public/image/2026/06/xxx.png
```

### PM2 部署

如果使用 PM2 部署，应用直接运行在宿主机上，建议把上传目录配置为宿主机绝对路径：

```dotenv
NUXT_UPLOAD_DIR=/www/sv-nuxt/uploads
NUXT_PUBLIC_UPLOAD_BASE=/uploads
```

Nginx 或宝塔静态映射仍然使用同样配置：

```nginx
location /uploads/ {
    alias /www/sv-nuxt/uploads/;
    access_log off;
    expires 30d;
}
```

如果上传文件目录改成了其他位置，需要同步调整 `NUXT_UPLOAD_DIR`、`NUXT_UPLOAD_HOST_DIR` 和 Nginx `alias` 路径，确保三者指向同一批实际文件。