# 快速上手

本文档将帮助您快速启动 DarkM 项目，从零到运行只需 10 分钟！

# 📋 前置要求

环境	版本要求	说明
.NET SDK	5.0+	下载链接 (opens new window)
Node.js	10+	下载链接 (opens new window)
IDE	VS2019+ / VS Code	推荐使用 Visual Studio 2019+
数据库	SQLite/SqlServer/MySql/PostgreSQL	默认使用 SQLite（无需安装）

# 🚀 获取源码

# 方式一：克隆示例仓库（推荐）

git clone https://glab.woowis.com/Woowis/DarkM.Demo.git
cd DarkM.Demo

1
2

# 方式二：使用代码生成器创建

参考创建模块文档

# ⚙️ 配置说明

配置文件位于 WebHost/appsettings.json，主要配置项如下：

# 1. 主机配置

{
  "Host": {
    "Urls": "http://*:6220",        // 监听地址和端口
    "Swagger": true,                 // 是否开启 Swagger
    "Proxy": false,                  // 是否启用代理
    "PreflightMaxAge": 1800          // 跨域预检请求有效期（秒）
  }
}

1
2
3
4
5
6
7
8

# 2. 数据库配置

{
  "Db": {
    "Logging": false,                // 是否记录 SQL 日志
    "Dialect": 2,                    // 数据库类型：0=SqlServer, 1=MySql, 2=SQLite, 3=PostgreSQL
    "Server": "../../data/SQLite",   // 数据库地址（SQLite 为文件路径）
    "Port": 0,                       // 端口号
    "UserId": "",                    // 用户名
    "Password": "",                  // 密码
    "CreateDatabase": true,          // 自动创建数据库和表
    "InitData": true,                // 自动初始化数据
    "Modules": [                     // 模块列表
      {
        "Name": "Admin",             // 模块名称
        "Database": "Nm_Admin",      // 数据库名称
        "Prefix": "",                // 表前缀
        "ConnectionString": ""       // 自定义连接字符串（可选）
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 3. 缓存配置

{
  "Cache": {
    "Provider": 0,                   // 缓存提供器：0=MemoryCache, 1=Redis, 2=Memcached
    "Redis": {
      "ConnectionString": "127.0.0.1:6379",
      "DefaultDb": 0,
      "Prefix": "DM"
    }
  }
}

1
2
3
4
5
6
7
8
9
10

# 4. 日志配置

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.log",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 30
        }
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 🎯 快速启动（SQLite 版）

默认配置使用 SQLite，无需安装数据库，最适合快速体验！

# 步骤 1：启动后端

# 进入 WebHost 目录
cd src/Admin/WebHost

# 运行项目
dotnet run

1
2
3
4
5

启动成功标志：

Now listening on: http://localhost:6220
Application started. Press Ctrl+C to shut down.

1
2

# 步骤 2：访问后端

Swagger API 文档: http://localhost:6220/swagger (opens new window)
健康检查: http://localhost:6220/health (opens new window)

# 步骤 3：启动前端

# 进入前端项目目录
cd src/Admin/UI/module-admin

# 安装依赖（首次运行需要）
npm install

# 启动开发服务器
npm run serve

1
2
3
4
5
6
7
8

启动成功标志：

App running at:
- Local:  http://localhost:5220/

1
2

# 步骤 4：访问前端

前端地址: http://localhost:5220/app/ (opens new window)
默认账号: admin / ******

# 🗄️ 使用其他数据库

# SqlServer 配置

{
  "Db": {
    "Dialect": 0,
    "Server": "192.168.1.100",
    "Port": 1433,
    "UserId": "sa",
    "Password": "YourPassword",
    "CreateDatabase": true
  }
}

1
2
3
4
5
6
7
8
9
10

# MySql 配置

{
  "Db": {
    "Dialect": 1,
    "Server": "127.0.0.1",
    "Port": 3306,
    "UserId": "root",
    "Password": "root",
    "CreateDatabase": true
  }
}

1
2
3
4
5
6
7
8
9
10

# PostgreSQL 配置

{
  "Db": {
    "Dialect": 3,
    "Server": "127.0.0.1",
    "Port": 5432,
    "UserId": "postgres",
    "Password": "postgres",
    "NpgsqlDatabaseName": "darkm"
  }
}

1
2
3
4
5
6
7
8
9
10

# 📦 发布部署

# 发布到服务器

# Windows

dotnet publish -r win-x64 -c Release --self-contained=false

# Linux

dotnet publish -r linux-x64 -c Release /p:PublishSingleFile=true

发布文件位于：bin/Release/net5.0/publish/

# 发布前端

cd src/Admin/UI/module-admin
npm run build

1
2

打包文件会自动复制到 WebHost/wwwroot/app/

# Docker 部署

# 构建镜像
docker build -t darkm/demo .

# 运行容器
docker run --name=dmdemo -p 6220:6220 -d darkm/demo

1
2
3
4
5

# IIS 部署（Windows Server）

前置要求：

Windows Server 2008 R2 SP1+
安装 KB2533623 补丁
安装 .NET 5.0 Hosting Bundle
安装 IIS URL Rewrite 模块

步骤：

发布后端到 IIS 目录
在 IIS 中创建应用程序池（.NET CLR 版本：无托管代码）
创建网站并指向发布目录
设置应用程序池身份权限

# 🔧 常见问题

# 1. 端口被占用

错误： Failed to bind to address http://localhost:6220

解决： 修改 appsettings.json 中的端口号

{
  "Host": {
    "Urls": "http://*:6221"
  }
}

1
2
3
4
5

# 2. 前端无法启动

错误： npm: command not found

解决： 安装 Node.js 并添加到 PATH

node -v  # 检查版本
npm -v   # 检查 npm 版本

1
2

# 3. 数据库创建失败

错误： Cannot create database

解决：

检查数据库服务是否运行
检查连接字符串是否正确
检查数据库用户权限

# 4. 跨域问题

错误： Access-Control-Allow-Origin

解决： 确保后端配置了正确的 CORS 策略

{
  "Host": {
    "PreflightMaxAge": 1800
  }
}

1
2
3
4
5

# 📚 下一步

模块化理念 - 了解设计思想
创建模块 - 使用代码生成器
安装模块 - 集成新模块
模块目录 - 查看所有可用模块

需要帮助？ 访问 GitHub Issues (opens new window) 或加入技术交流群

最后更新: 2022-08-07

← 模块化创建一个模块 →