# nan-admin

**Repository Path**: LittleY98/nan-admin

## Basic Information

- **Project Name**: nan-admin
- **Description**: nan-admin...
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# nan-admin

基于 [ContiNew Admin](https://github.com/continew-org/continew-admin) 二次开发的后台管理系统，当前版本 **v0.0.1**。

- 应用 ID / Maven artifactId：`nan-admin`
- Maven groupId / Java 基础包：`com.nan.admin`
- 启动类：`com.nan.admin.NanAdminApplication`
- 基线：上游开发版本 `4.2.0-SNAPSHOT`，起始 commit `d0344cb3`
- Java 17+，使用仓库内 Maven Wrapper（3.9.16）
- 前端位于 `continew-admin-ui/`，包名 `nan-admin-ui`，使用 Node.js 22、pnpm 9.3.0。

## 业务开发与 AI 协作

- [AGENTS.md](AGENTS.md)：所有编程工具共用的工程约定、边界和验证要求。
- [业务开发指南](docs/development.md)：从需求到迁移、接口、页面、权限和验收的完整流程。
- [需求模板](docs/templates/feature.md)：复杂功能可直接填写，作为后续开发上下文。
- [前端 AGENTS.md](continew-admin-ui/AGENTS.md)：前端组件、路由、API 和认证约定。

先描述业务目标、使用角色、字段规则和验收场景，AI 再结合当前代码实现；不依赖特定模型或 IDE。仓库文档以当前 nan-admin 实现为准，上游示例需要适配。

## 本地 Docker 启动

确保 Docker 已启动，在仓库根目录执行：

```bash
./mvnw verify
cd continew-admin-ui
corepack pnpm install --frozen-lockfile
corepack pnpm build
cd ..
docker compose -f docker/docker-compose.yml up -d --build
```

Compose 会启动新的 MySQL、Redis、后端和 Nginx 前端容器，项目名为 `nan-admin`，数据保存在独立命名卷中。

| 服务 | 本地地址 | 说明 |
| --- | --- | --- |
| 前端 | http://localhost:5173 | nan-admin 登录页面 |
| 后端 | http://localhost:8000 | 根路径返回应用信息 |
| API 文档 | http://localhost:8000/doc.html | 开发环境开放 |
| MySQL | 127.0.0.1:13306 | 数据库名 `nan-admin`，用户 `nan_admin` |
| Redis | 127.0.0.1:16379 | DB 0 |
| 占位 Logo | http://localhost:8000/branding/logo.svg | 前后端共用占位标识 |

默认本地开发密码：MySQL 应用用户 `nan_admin_dev`、root `nan_root_dev`、Redis `nan_redis_dev`。这些值仅用于本地开发。需要覆盖时，将 `docker/.env.example` 复制为 `docker/.env` 后修改；该文件不会提交到 Git。

默认后台账号沿用初始化数据：`admin / admin123`。

首次启动时，MySQL 自动创建 `nan-admin` 数据库，后端通过 Liquibase 创建表并应用初始化数据。直接编写 SQL 引用该库时使用反引号包裹库名，例如 ``USE `nan-admin`;``。

```bash
# 查看状态、后端日志
docker compose -f docker/docker-compose.yml ps
docker compose -f docker/docker-compose.yml logs -f server

# 停止容器，保留数据卷
docker compose -f docker/docker-compose.yml down
```

## 在 IDE 中运行后端

只启动基础服务：

```bash
docker compose -f docker/docker-compose.yml up -d mysql redis
```

若 Docker 后端已经在运行，先执行 `docker compose -f docker/docker-compose.yml stop server`，再在 IDE 中运行 `NanAdminApplication`。使用 JDK 17 或更新版本、dev profile、仓库根目录作为工作目录。

dev 配置默认连接上述 `13306` / `16379` 端口，无需额外设置。若修改了 `docker/.env`，还需在 IDE 中配置相同的 `DB_PORT`、`DB_USER`、`DB_PWD`、`REDIS_PORT`、`REDIS_PWD`；Spring 不会自动读取 Compose 的 `.env` 文件。

前端默认 Origin 为 `http://localhost:5173`，Refresh Cookie 也允许 `http://localhost:5777`。切换前端端口时需同步调整开发环境配置中的来源白名单。

## 前端本地开发

先启动 Compose 中的基础服务和后端，再运行 Vite：

```bash
docker compose -f docker/docker-compose.yml up -d mysql redis server
# 如果已经启动 Docker 前端，释放 5173 端口
docker compose -f docker/docker-compose.yml stop web
cd continew-admin-ui
corepack pnpm install --frozen-lockfile
corepack pnpm dev
```

访问 `http://localhost:5173`。Vite 将 `/api` 请求转发至 `http://localhost:8000`，WebSocket 直接连接后端。修改前端环境变量后需重启 Vite；Docker 使用构建产物，需重新 `pnpm build` 并执行 `docker compose -f docker/docker-compose.yml up -d --build web`（在仓库根目录执行）。详细说明见 [前端 README](continew-admin-ui/README.md)。

## 二开范围

已完成模块前缀 `nan-*`、Java 包 `com.nan.admin`、应用信息、启动 Banner、占位 Logo 和本地存储路径的改造。Maven / 应用配置版本使用 `0.0.1`，展示版本为 `v0.0.1`。

暂不接入第三方登录、邮件、短信、对象存储或 Snail Job 调度中心。默认客户端仅允许账号密码登录；文件使用本地存储，公告发布保留本地定时任务。多租户、认证会话、权限、能力开放和代码生成等模块保留，后续按业务需求裁剪。独立调度服务端代码保留为可选模块，Compose 不启动它。

已移除演示环境数据重置执行器、上游截图以及面向上游的部署、Sonar、欢迎和机器人审查 workflow；保留 CI、质量门禁和源码中的原有版权声明。上游数据库历史和系统种子数据保留，通过新增 `nan_admin.sql` 增量调整品牌、存储及默认登录方式。

Logo 位于 `nan-server/src/main/resources/static/branding/logo.svg`，前端占位 Logo / favicon 位于 `continew-admin-ui/public/`。前端标题、品牌回退值和构建信息均已同步；已移除统计脚本、广告、上游动态和关于页，仅展示账号登录入口。数据库中的品牌默认值指向本地后端地址。系统配置中已经手动设置的品牌值优先于默认值，不会被迁移覆盖。

## 模块

| 模块 | 职责 |
| --- | --- |
| `nan-server` | 应用入口、配置、数据库迁移和打包 |
| `nan-common` | 公共 API、上下文、工具及配置 |
| `nan-auth-refresh` | 认证会话与刷新令牌 |
| `nan-system` | 认证、用户、角色、菜单等系统业务 |
| `nan-plugin` | 租户、能力开放、调度、代码生成插件 |
| `nan-extension` | 可选的独立调度服务端 |

新增业务模块时，在根 POM 的 `modules` 和 `dependencyManagement` 注册，再按需由 server 引入。第三方依赖版本继续由 ContiNew Starter 管理，不修改其坐标和包名。

## 构建与数据库变更

```bash
./mvnw verify
# 只有格式检查失败时使用，修复后重新 verify
./mvnw compile -Pformat
./mvnw verify
```

完整构建执行 Enforcer、Spotless、Checkstyle、SpotBugs，以及已启用的模块单元测试。默认产物在 `nan-server/target/app/`，Docker 镜像使用该目录，因此修改代码后需重新构建，再执行 Compose 的 `up -d --build`。

数据库变更使用 Liquibase，保留既有变更集，并同步提供 MySQL / PostgreSQL 脚本。当前默认使用 MySQL；PostgreSQL 入口在主 changelog 中保留为注释，需要切换数据源及相应 include 后使用。

当前 Compose 仅用于本地 dev 环境，使用 Nginx 托管前端和代理 API，不含域名、TLS 或生产部署配置。生产配置中的凭据仍要求环境变量显式注入。

## 上游与许可

原项目：[ContiNew Admin](https://github.com/continew-org/continew-admin)。原始许可文本见 [上游 LICENSE](https://github.com/continew-org/continew-admin/blob/dev/LICENSE)，源码保留原作者版权声明；`CHANGELOG.md` 为上游历史记录。