快速开始

环境要求

安装依赖

pnpm install

开发模式

方式一：并发启动（推荐）

使用单个命令同时启动前后端：

# 同时启动后端（端口 3001）与前端（端口 5173）
pnpm dev

访问地址：http://localhost:5173

首次启动提示：如果系统尚未初始化，请访问初始化向导 http://localhost:5173/setup 配置数据库并创建首个管理员。

方式二：独立启动

在独立终端中分别启动前后端：

# 终端 1 - 仅后端（端口 3001）
cd server && pnpm dev

# 终端 2 - 仅前端（端口 5173）
cd client && pnpm dev

生产构建

pnpm build

源码运行 - 聚合模式（单端口）

前后端在同一个端口（3001）运行：

# 步骤 1：先构建前端
pnpm --filter client build

# 步骤 2：仅启动后端（同时提供 API 和前端页面，端口 3001）
cd server && pnpm dev

访问地址：http://localhost:3001

环境变量

将 .env.example 复制为 server/.env：

cp server/.env.example server/.env
变量 默认值 说明
PORT 3001 服务端端口
NODE_ENV development 运行环境
JWT_SECRET 未设置 JWT 基础密钥
DB_PATH ./dnsmgr.db SQLite 数据库路径
DB_TYPE sqlite 数据库类型
DB_HOST - 数据库主机
DB_PORT - 数据库端口
DB_NAME - 数据库名称
DB_USER - 数据库用户
DB_PASSWORD - 数据库密码
DB_SSL false 启用 SSL

Docker 部署

使用预构建镜像

docker run -d \
  -p 3001:3001 \
  -v $(pwd)/data:/app/data \
  --name dnsmgr \
  ghcr.io/hipm-tech/dnsmgr:latest

Docker Compose

# 下载编排文件
curl -O https://raw.githubusercontent.com/HiPM-Tech/DNSMgr/main/docker-compose.yml

# 启动服务
docker-compose up -d

初始化流程

  1. 首次访问系统时，会自动跳转到初始化向导
  2. 配置数据库连接（SQLite/MySQL/PostgreSQL）
  3. 创建超级管理员账户
  4. 使用管理员账户登录系统

开发规范

数据库操作

必须使用业务适配器层的业务操作模块：

// ✅ 正确 - 使用业务操作模块
import { UserOperations, DomainOperations } from '../db';

const user = await UserOperations.getById(1);
const domains = await DomainOperations.getByAccountId(accountId);

// ❌ 错误 - 禁止在业务代码中直接编写 SQL
const user = await query<User>('SELECT * FROM users WHERE id = ?', [userId]);

// ❌ 错误 - 禁止使用已废除的兼容层
import { getAdapter } from '../db/adapter';
const db = getAdapter();

重要原则：业务代码只能通过业务操作模块（如 UserOperations, DomainOperations 等）访问数据库，禁止直接调用 query, get, execute 等底层函数。

代码风格