# DTCMS

**Repository Path**: hcj/dtcms

## Basic Information

- **Project Name**: DTCMS
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DiTing CMS 使用与部署文档

本文档面向两类读者：
- **使用者 / 运维人员**：希望在一台新机器上部署并运行本系统。
- **开发者**：希望在本地启动、初始化、维护和更新项目。

> 本文档基于当前代码仓库实际结构编写，可用于从 0 到 1 部署一套新的 `DiTing CMS` 实例。

---

## 1. 项目简介

`DiTing CMS` 是一个基于以下技术栈构建的全栈内容管理系统：
- `Next.js 16`
- `React 19`
- `TypeScript`
- `Drizzle ORM`
- `MySQL`
- `NextAuth`（账号密码登录）
- 可选本地存储 / S3 兼容对象存储

系统包含：
- 前台站点
- 后台管理系统
- 文章、页面、分类、标签、评论、导航、轮播图、媒体库管理
- SEO 配置
- 外观主题与主题色配置
- 本地上传和 S3 上传切换

---

## 2. 部署方式说明

当前项目最适合以下部署模型：

### 2.1 推荐部署模型
- **应用服务**：Node.js 运行 `Next.js` 生产服务
- **数据库**：MySQL 8+
- **反向代理**：Nginx / Caddy / 宝塔站点代理（可选但强烈推荐）
- **进程守护**：PM2 / systemd（Linux）
- **媒体存储**：
  - 简单场景：本地 `public/uploads`
  - 生产推荐：S3 兼容对象存储

### 2.2 当前仓库的重要现实情况
本项目当前：
- **有数据库 schema 定义**：`src/db/schema.ts`
- **有种子脚本**：`src/db/seed.ts`、`src/db/seed-demo.ts`
- **有 Drizzle 配置**：`drizzle.config.ts`
- **没有成套版本化迁移文件**

因此在新机器初始化数据库时，推荐使用：

```bash
npx drizzle-kit push
```

该命令会根据 `src/db/schema.ts` 将表结构同步到目标数据库。

---

## 3. 目录说明

当前与部署最相关的目录如下：

```text
src/app/                 Next.js 页面与 API
src/app/api/             API 路由
src/db/                  数据库连接、schema、seed 脚本
src/lib/                 业务逻辑、存储、图片处理等
public/                  静态资源
public/uploads/          本地上传目录（运行中自动创建）
drizzle.config.ts        Drizzle 配置
package.json             项目脚本与依赖
```

---

## 4. 环境要求

建议新机器满足以下条件。

### 4.1 基础软件版本
- `Node.js 20 LTS` 或更高
- `npm 10+`
- `MySQL 8.0+`
- Linux 生产环境建议：
  - `Ubuntu 22.04+` / `Debian 12+` / `CentOS Stream 9+`
  - `Nginx`
  - `PM2`

### 4.2 硬件建议
最小可运行配置：
- 2 vCPU
- 2 GB RAM
- 20 GB SSD

推荐生产配置：
- 2~4 vCPU
- 4 GB RAM
- 40 GB SSD
- 独立 MySQL 或云数据库

---

## 5. 新机器部署前准备

在正式部署前，请先准备以下信息：

### 5.1 域名
例如：
- 前台域名：`https://cms.example.com`

系统中的 sitemap、robots、登录回调等会依赖站点地址，因此生产环境必须配置正确的站点 URL。

### 5.2 数据库连接信息
需要准备一个空的 MySQL 数据库，例如：
- 数据库地址：`127.0.0.1`
- 端口：`3306`
- 数据库名：`dtcms`
- 用户名：`dtcms_user`
- 密码：`your_password`

### 5.3 认证密钥
需要准备一段高强度随机字符串，作为会话/认证密钥。

生成示例：

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

### 5.4 媒体存储方案
部署前只需要明确你准备使用哪种方案：
1. **本地存储**：上传文件写入服务器本地磁盘
2. **S3 兼容存储**：如 AWS S3、Cloudflare R2、阿里云 OSS（兼容模式）、腾讯云 COS（兼容模式）

具体的存储类型选择和 S3 参数填写，统一在系统部署完成后通过后台“存储设置”写入数据库。

---

## 6. 获取项目代码

在新机器上执行：

```bash
git clone <你的仓库地址> dtcms
cd dtcms
```

安装依赖：

```bash
npm install
```

> 如果你是通过压缩包分发代码，也可以直接解压后进入项目目录执行 `npm install`。

---

## 7. 环境变量配置

项目根目录创建 `.env` 文件。

推荐最小生产配置如下：

```env
# 站点公网访问地址
NEXTAUTH_URL=https://cms.example.com

# NextAuth / 会话密钥
AUTH_SECRET=请替换为随机长字符串

# MySQL 连接串
DATABASE_URL=mysql://dtcms_user:your_password@127.0.0.1:3306/dtcms

# 可选：图片处理时附加水印文件路径
# WATERMARK_PATH=/opt/dtcms/watermark.png
```

> 说明：媒体存储类型以及 S3 相关参数已改为在后台“存储设置”中写入数据库管理，不再通过 `.env` 配置。

### 7.1 各环境变量说明

#### `NEXTAUTH_URL`
系统对外访问的完整地址，例如：

```env
NEXTAUTH_URL=https://cms.example.com
```

用途：
- 登录相关 URL 生成
- `robots.ts` 生成 sitemap 地址
- `sitemap.ts` 生成页面绝对地址

#### `AUTH_SECRET`
NextAuth 使用的认证密钥。必须设置为高强度随机字符串。

#### `DATABASE_URL`
MySQL 连接串格式：

```env
DATABASE_URL=mysql://用户名:密码@主机:端口/数据库名
```

示例：

```env
DATABASE_URL=mysql://dtcms_user:StrongPassword123@127.0.0.1:3306/dtcms
```

#### 媒体存储方式
媒体文件默认支持两种模式：
- `local`：上传到本机 `public/uploads`
- `s3`：上传到对象存储

媒体存储类型以及 S3 相关参数不再通过 `.env` 管理，而是在系统后台的“存储设置”页面写入数据库。

#### `WATERMARK_PATH`
可选。若设置，则图片处理流程会尝试读取该文件作为水印图，并添加到图片右下角。

请注意：
- 文件路径必须真实存在
- Node 进程必须有读取权限
- 如果路径错误，系统会跳过水印并记录警告日志

#### 媒体存储配置说明
媒体存储类型以及 S3 相关参数不再通过 `.env` 管理，而是在系统后台的“存储设置”页面写入数据库。

部署后的配置方式为：
- 先用最小 `.env` 启动系统
- 使用管理员账号登录后台
- 进入“系统设置” -> “存储设置”
- 在后台选择本地存储或 S3，并填写对应参数

---

## 8. 初始化数据库

### 8.1 创建数据库
先在 MySQL 中创建数据库：

```sql
CREATE DATABASE dtcms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

也建议创建独立用户并授权：

```sql
CREATE USER 'dtcms_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON dtcms.* TO 'dtcms_user'@'%';
FLUSH PRIVILEGES;
```

### 8.2 推送 schema 到数据库
由于当前仓库没有完整迁移链，首次部署请直接执行：

```bash
npx drizzle-kit push
```

执行成功后，`src/db/schema.ts` 中定义的表会同步到目标数据库。

### 8.3 写入初始管理员账号
执行：

```bash
npm run db:seed
```

该脚本会创建/更新一个管理员账号。

默认初始账号为：
- 邮箱：`admin@metis.com`
- 密码：`Admin@2026`

> **强烈建议**：首次登录后台后立即修改此密码。

### 8.4 写入演示数据（可选）
如果你希望快速看到完整前后台效果，可继续执行：

```bash
npm run db:seed-demo
```

该脚本会写入：
- 分类
- 标签
- 演示文章
- 页面
- 菜单
- 基础站点设置
- 轮播图等演示数据

如果你部署的是正式生产环境，且不需要演示内容，可以跳过这一步。

---

## 9. 本地开发启动方式

用于开发或调试：

```bash
npm run dev
```

默认访问地址：

```text
http://localhost:3000
```

开发模式特征：
- 代码热更新
- 适合开发调试
- 不适合生产环境

---

## 10. 生产环境启动方式

### 10.1 构建项目

```bash
npm run build
```

### 10.2 启动生产服务

```bash
npm run start
```

默认会监听 `3000` 端口。

你可以通过以下方式指定端口：

```bash
set PORT=3000 && npm run start
```

Linux/macOS：

```bash
PORT=3000 npm run start
```

---

## 11. 推荐生产部署方案（Linux + PM2 + Nginx）

以下是一套适合新机器落地的标准部署流程。

---

### 11.1 安装系统依赖
以 Ubuntu 为例：

```bash
sudo apt update
sudo apt install -y nginx mysql-client
sudo npm install -g pm2
```

> 如果 MySQL 与应用在同一台机器，也请先安装并初始化 MySQL 服务。

---

### 11.2 创建部署目录

```bash
sudo mkdir -p /opt/dtcms
sudo chown -R $USER:$USER /opt/dtcms
cd /opt/dtcms
```

然后拉取代码：

```bash
git clone <你的仓库地址> app
cd app
npm install
```

---

### 11.3 配置 `.env`

```bash
nano .env
```

填入前文第 7 节中的配置。

---

### 11.4 初始化数据库

```bash
npx drizzle-kit push
npm run db:seed
# 如需演示数据，再执行：
# npm run db:seed-demo
```

---

### 11.5 构建生产包

```bash
npm run build
```

---

### 11.6 使用 PM2 启动

```bash
pm2 start npm --name dtcms -- start
pm2 save
pm2 startup
```

查看状态：

```bash
pm2 status
```

查看日志：

```bash
pm2 logs dtcms
```

重启服务：

```bash
pm2 restart dtcms
```

停止服务：

```bash
pm2 stop dtcms
```

---

### 11.7 配置 Nginx 反向代理
创建站点配置，例如：

```bash
sudo nano /etc/nginx/sites-available/dtcms.conf
```

写入：

```nginx
server {
    listen 80;
    server_name cms.example.com;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}
```

启用站点：

```bash
sudo ln -s /etc/nginx/sites-available/dtcms.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

---

### 11.8 配置 HTTPS
建议使用 `Certbot`：

```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d cms.example.com
```

申请完成后，请再次确认 `.env` 中：

```env
NEXTAUTH_URL=https://cms.example.com
```

如果域名或协议发生变化，记得：
- 修改 `.env`
- 重启 Node 服务

```bash
pm2 restart dtcms
```

---

## 12. Windows 服务器部署说明

如果你在 Windows Server 上部署，可采用以下方式：

### 12.1 安装内容
- Node.js 20+
- MySQL 8+
- Git
- 可选：IIS / Nginx / Caddy 做反向代理
- 可选：PM2（Windows 可用，但一般不如 Linux 常见）

### 12.2 部署步骤
在项目目录执行：

```powershell
npm install
npx drizzle-kit push
npm run db:seed
npm run build
npm run start
```

如需长期驻留运行，建议：
- 使用 Windows 服务包装器
- 或使用 PM2
- 或放到 IIS 反向代理后面

### 12.3 本地目录权限
如果使用本地上传，请确保：
- 运行 Node 进程的账户对项目目录有写权限
- 尤其对 `public/uploads` 可写

---

## 13. 首次登录与初始化操作

部署完成后，访问：

```text
https://你的域名/login
```

使用初始账号登录：
- 邮箱：`admin@metis.com`
- 密码：`Admin@2026`

首次进入后台后建议按以下顺序完成初始化：

1. 修改管理员密码
2. 打开“系统设置”完善：
   - 站点名称
   - 副标题
   - 页脚版权
3. 打开“SEO 设置”填写：
   - `seo_keywords`
   - `seo_description`
4. 打开“主题 / 外观”设置：
   - 布局主题
   - 主题色
   - 字体
   - 圆角风格
5. 打开“存储设置”并完成媒体存储配置：
   - 选择本地存储或 S3
   - 如使用 S3，填写 Access Key、Secret、Bucket、Endpoint、Public URL 等参数
6. 创建正式分类、文章、页面、菜单
7. 如使用演示数据，请删除不需要的内容

---

## 14. 媒体上传与存储说明

### 14.1 本地存储模式
当你在后台“存储设置”中选择本地存储时，上传文件将写入：

```text
public/uploads/
```

特点：
- 配置简单
- 成本低
- 适合单机部署

注意事项：
- 迁移服务器时必须同步该目录
- 做备份时必须包含该目录
- 多机部署时不适合直接使用本地存储

### 14.2 S3 存储模式
当你在后台“存储设置”中选择 S3 并保存参数后，系统会使用对象存储保存媒体文件。

适合：
- 云服务器部署
- 多机部署
- 前后端分离或 CDN 场景

建议同时配置：
- 独立 bucket
- 公网访问域名或 CDN 域名
- 合理的 bucket 权限策略

---

## 15. 图片处理说明

上传图片时，系统会执行以下逻辑：
- 非 SVG 图片会尝试进入图片处理流程
- 可按后台配置决定压缩质量与输出格式
- 如配置了 `WATERMARK_PATH`，会尝试添加水印

因此生产环境请确认：
- 服务器支持 `sharp`
- 水印图路径真实存在（如启用）
- 服务器 CPU / 内存足以处理较大图片

如果图片处理失败，系统会退回使用原始文件并输出警告日志。

---

## 16. 常用运维命令

### 16.1 安装依赖

```bash
npm install
```

### 16.2 开发模式启动

```bash
npm run dev
```

### 16.3 生产构建

```bash
npm run build
```

### 16.4 生产运行

```bash
npm run start
```

### 16.5 初始化管理员账号

```bash
npm run db:seed
```

### 16.6 写入演示数据

```bash
npm run db:seed-demo
```

### 16.7 同步数据库结构

```bash
npx drizzle-kit push
```

---

## 17. 升级发布流程

如果你后续需要在已部署服务器上更新代码，推荐流程如下：

```bash
cd /opt/dtcms/app
git pull
npm install
npx drizzle-kit push
npm run build
pm2 restart dtcms
```

如果这次更新包含：
- 数据库结构变更
- 新增配置项
- 媒体存储调整

请在发布前先在测试环境验证。

---

## 18. 备份与恢复

### 18.1 必须备份的内容
至少备份以下两部分：

1. **MySQL 数据库**
2. **媒体文件**
   - 若本地存储：备份 `public/uploads`
   - 若 S3 存储：确保 bucket 有版本管理或定期备份策略

### 18.2 MySQL 备份示例

```bash
mysqldump -u dtcms_user -p dtcms > dtcms.sql
```

### 18.3 MySQL 恢复示例

```bash
mysql -u dtcms_user -p dtcms < dtcms.sql
```

### 18.4 本地上传目录备份示例

```bash
tar -czf uploads-backup.tar.gz public/uploads
```

---

## 19. 故障排查

### 19.1 `DATABASE_URL` 无法连接
表现：
- 启动时报数据库连接错误
- 页面 500
- seed 脚本执行失败

检查：
- MySQL 是否启动
- 账号密码是否正确
- IP / 端口是否允许访问
- 数据库是否存在

### 19.2 登录后仍无法进入后台
检查：
- `.env` 中 `AUTH_SECRET` 是否配置
- `NEXTAUTH_URL` 是否正确
- 浏览器 Cookie 是否被代理层异常处理
- 反向代理是否透传了 `Host` / `X-Forwarded-Proto`

### 19.3 上传失败
检查：
- 本地上传时，`public/uploads` 是否可写
- S3 模式时，access key / secret / endpoint / bucket 是否正确
- 上传文件是否过大
- Nginx 是否配置了足够的 `client_max_body_size`

### 19.4 图片处理失败
检查：
- `sharp` 是否正常安装
- `WATERMARK_PATH` 指向的文件是否存在
- 原图格式是否异常

### 19.5 sitemap 或 robots 地址错误
检查：
- `.env` 中 `NEXTAUTH_URL` 是否为最终公网地址
- 修改后是否已重启服务

### 19.6 首次打开首页报数据库相关错误
可能原因：
- 数据库未初始化
- 还未执行 `npx drizzle-kit push`
- 还未执行 `npm run db:seed`

---

## 20. 安全建议

生产环境请务必执行以下操作：

1. **修改默认管理员密码**
2. **使用 HTTPS**
3. **限制 MySQL 外网访问**
4. **将 `.env` 排除在公开仓库之外**
5. **定期备份数据库与上传文件**
6. **使用非 root 数据库用户**
7. **如果使用 S3，配置最小权限访问策略**
8. **反向代理层限制上传体积、防刷和异常请求**

---

## 21. 建议的正式上线检查清单

上线前请逐项确认：

- [ ] 已安装 Node.js、npm、MySQL
- [ ] 已正确配置 `.env`
- [ ] `DATABASE_URL` 可连接
- [ ] 已执行 `npx drizzle-kit push`
- [ ] 已执行 `npm run db:seed`
- [ ] 已成功 `npm run build`
- [ ] 已通过 `npm run start` 正常启动
- [ ] 已配置 Nginx / HTTPS
- [ ] `NEXTAUTH_URL` 为正式域名
- [ ] 已能正常登录后台
- [ ] 已修改默认管理员密码
- [ ] 已检查上传功能
- [ ] 已检查文章发布与前台访问
- [ ] 已检查 sitemap / robots
- [ ] 已配置备份策略

---

## 22. 从零部署的最短命令清单

如果你已经熟悉 Linux 运维，可以按下面最短流程部署：

```bash
git clone <你的仓库地址> dtcms
cd dtcms
npm install

# 创建 .env 后执行
npx drizzle-kit push
npm run db:seed
npm run build
npm run start
```

生产推荐再配合：
- `PM2`
- `Nginx`
- `HTTPS`
- 数据库备份
- 上传目录或对象存储备份

---

## 23. 当前项目已知部署特性说明

为了避免部署时误解，这里明确说明当前代码的几个特点：

1. **数据库初始化依赖 `drizzle-kit push`，而不是版本化迁移链**。
2. **默认管理员账号由 `npm run db:seed` 创建**。
3. **演示内容由 `npm run db:seed-demo` 写入**。
4. **系统设置、SEO、主题、存储等很多业务配置保存在数据库 `settings` 表中，而不是 `.env`**。
5. **本地上传目录默认是 `public/uploads`，目录会在运行中自动创建，但必须保证进程有写权限**。
6. **站点对外 URL 依赖 `NEXTAUTH_URL`，配置错误会影响登录、robots、sitemap 等行为**。
7. **S3 对象存储配置已改为后台“存储设置”写入数据库，不再从 `.env` 读取**。

---

## 24. 维护建议

如果你计划长期维护本项目，建议后续补充这些内容：
- 增加 `.env.example`
- 增加正式数据库迁移流程
- 增加 Docker / Docker Compose 部署文件
- 增加 CI/CD 发布流程
- 增加健康检查与监控告警

---

如果你希望，我下一步还可以继续帮你补两项内容：
1. 生成一份可直接复制使用的 `.env.example`
2. 再补一份 `Docker / Docker Compose` 部署文档