项目结构

在 配置说明 中，我们介绍了配置的三个来源；在 静态资源 中，也说明了 public/ 的内容。本节继续介绍其余目录及其职责，便于后续修改时定位对应文件。

总览

目录树imqi1-cms/
├── app/                   前端（Nuxt 4）
├── server/                服务端（Nitro）
├── shared/                前端与服务端共享的代码
├── test/                  测试
├── prisma/                数据库表定义
├── scripts/               运维与部署脚本（独立子包）
├── docker/                镜像与容器编排
├── mini/                  小程序端（git 子模块）
├── public/                静态资源
├── lib/                   站点配置的类型定义
├── nuxt.config.ts         Nuxt 配置
├── site.config.ts         站点配置
└── .env.example           环境变量模板

.env 与 site.config.ts 已在 配置说明 中介绍，public/ 已在 静态资源 中介绍。下面说明其余目录。

app/

app/ 是 Nuxt 4 的前端目录，页面、组件与样式的修改均从这里开始：

目录树app/
├── app.vue                根组件
├── pages/                 页面路由
├── components/            组件
├── composables/           组合式函数
├── utils/                 工具函数
├── lib/                   前端私有库
├── plugins/               插件
├── middleware/            前端路由中间件
├── directives/            自定义指令
├── assets/                构建期素材
├── shiki/                 代码高亮主题
├── types/                 前端类型
└── router.options.ts      路由选项

说明：

• app.vue：根组件
• pages/、components/：Vue 组件，前者被 Nuxt 文件式路由使用，如 pages/index.vue 是首页、后台各页面在 pages/admin/；后者被其他组件引用复用
• composables/：组合式函数，命名统一 useXxx，返回的值中可含 ref
• utils/：工具函数
• lib/：前端私有库，站点的 APlayer 音乐播放器实现与 cn 类名合并工具在这里
• plugins/：插件，防镜像与站点设置预取都在这层
• middleware/：前端路由中间件，目前只有 auth.global，用于未登录时跳转到登录页
• directives/：自定义指令，目前只有 scrollReveal，实现滚动入场渐入效果
• assets/：构建期素材，css/main.css 定义字体与颜色变量，emojis.json 是评论区表情映射
• shiki/：两套自定义的代码高亮主题
• types/：前端类型
• router.options.ts：路由选项

server/

server/ 是 Nitro 服务端目录，接口、中间件与服务端工具均位于此处：

目录树server/
├── api/                   /api/* 接口
├── routes/                不走 /api 的服务端路由
├── middleware/            服务端中间件
├── plugins/               Nitro 插件
├── utils/                 服务端工具
├── runtime-assets/        运行时资产
├── types/                 服务端类型
└── lib/                   服务端私有模块

说明：

• api/、routes/：都用于服务端接口，前者走 /api/* 路径，后者直接走根路径，通常用于 RSS 订阅源、sitemap.xml 这类固定端点
• middleware/：同步的请求级中间件，如 referer 白名单与小程序接口鉴权（在 环境变量说明 里已说明）
• plugins/：负责在服务端运行时注入额外的功能，如 CSP 响应头、SSR 内部请求密钥与 RSS 订阅的定时刷新
• utils/：服务端工具，按职责划分，数据库操作、邮件发送、评论头像、内容缓存、附件上传、COS 会话存储等
• runtime-assets/：随包运行的二进制资产，目前是 IP 归属地数据库与验证码字体，构建后由 copy-data.ts 复制进产物

新增接口时请遵循两项全仓统一的规则：对外查询接口应参照现有接口使用 select 选择返回字段，后台写接口必须通过 CSRF 校验。

shared/

shared/ 存放前端与服务端共用的代码。构建时 app 与 server 会各自内联一份，因此这里只放纯函数与常量，不存放仅在运行时有意义的状态。目前包含 Redis 连接配置的读取与降级、评论区表情分组、高德代理、城市坐标、HTML 过滤等模块。

test/

test/ 存放自动化测试，使用 bun 内置的 bun:test，运行方式见 测试。unit/ 单元测试按 app/、server/、shared/ 镜像源码目录，unit/real/ 测试真实实现；integration/ 集成测试使用 .env 中的数据库连接，其中 db/ 直接验证 Prisma 查询与约束，real/ 走真实 handler 流程并在 ${DB_NAME}_test 旁路库（TEST_DB_NAME 可覆盖）建表；e2e/ 是 Playwright 端到端测试，依赖在 test/package.json 中独立管理；helpers/、types/ 与 zz-late/ 是测试替身、类型声明和防 mock 泄漏的兜底用例，保持在顶层。

prisma/

prisma/ 只有一个 schema.prisma，全部数据表均定义在这里。文章、评论、分类标签、友链、订阅、旅行地点、站点设置、用户与会话都在其中。如需直观查看数据，可使用 bun run prisma:studio 打开图形化界面。

scripts/

scripts/ 是独立的子包，拥有自己的 package.json。其依赖不会随根目录的 bun install 安装，首次运行相关命令前需执行一次 bun run scripts:install。每个脚本对应一条 bun run 命令：

目录树scripts/
├── init-db.ts              初始化数据库（bun run db:init）
├── init-db.sql             建表与种子数据，供 pgadmin 手动导入
├── reset-password.ts       重置管理员密码（bun run reset:password）
├── reset-2fa.ts            重置两步验证（bun run reset:2fa）
├── upload-cos.ts           静态资源上传 COS（bun run upload:cos）
├── upload-server.ts        构建产物上传服务器（bun run upload:server）
├── compress-livephoto.ts   压缩实况照片（bun run compress:livephoto）
├── generate-nginx-conf.ts  生成 nginx 配置片段（bun run nginx:generate）
├── restart-server.ts       通过宝塔面板重启项目（bun run restart:server）
├── clear-redis.ts          清空 Redis（bun run clear:redis）
├── check-updates.ts        检查依赖更新（bun run check:update）
├── get-ip.ts               查询 IP 归属地（bun run get:ip）
├── tailwindcss-lint.ts     Tailwind 样式校验（bun run tailwindcss:lint）
├── test.ts                 测试入口，参数透传给 bun test（bun run test）
├── lint.ts                 ESLint 校验入口（bun run lint / lint:fix）
├── copy-data.ts            构建后自动执行
├── update-sw-cdn.ts        构建后自动执行
├── audit-shared-session.sh 登录一次缓存后台会话，供并行审计共用（bash 手动运行）
├── audit-api-check.sh      用共享会话并行检查后台接口（bash 手动运行）
├── export-bundle.sh        导出 Docker 构建产物（bun run export:bundle）
└── file-server.ts          本地附件文件服务（bun run serve）

各脚本用到的环境变量都收录在 环境变量说明 里。

docker/

docker/ 里是两份镜像定义与两套编排。Dockerfile 与 docker-compose.yml 带 Redis，Dockerfile.noredis 与 docker-compose.noredis.yml 不带，用法见 Docker 部署。

mini/

小程序端是独立的 uni-app 项目，源码位于 src/ 下，样式使用 UnoCSS，支持 H5、微信和支付宝三端。它以 git 子模块形式挂载在仓库中，并指向另一个独立仓库。快速开始 中的克隆命令已包含 --recurse-submodules；从旧克隆更新后，如 mini/ 为空目录，执行一次 git submodule update --init --recursive 即可。小程序拥有独立的 site.config.ts 与 .env，主站配置不会作用于小程序端。

其他文件

其余文件的职责如下：nuxt.config.ts 负责 Nuxt 与 Nitro 的整体配置，构建哈希、CDN 前缀、ISR 缓存规则与 PWA 均在这里配置；lib/site-config.ts 定义 site.config.ts 六个区的类型，并由 defineSiteConfig 校验；prisma.config.ts 是 Prisma 配置文件；eslint.config.mjs、tsconfig.json、components.json 与 bun.lock 用于代码规范和依赖锁定，日常无需修改。