# eauth

**Repository Path**: efucloud/eauth

## Basic Information

- **Project Name**: eauth
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EAuth（易认证）

[中文](./README.md) | [English](./README.en.md)

EAuth 是面向企业应用的统一认证与身份管理后端。它既可作为 OAuth 2.0 / OpenID Connect 身份提供方，为业务系统签发和验证令牌，也可连接 OIDC、LDAP、SAML 等外部身份源，为多个应用提供统一登录入口和认证策略。

前端控制台位于 [efucloud/eauth-console](https://github.com/efucloud/eauth-console)。

## 核心能力

- OAuth 2.0 / OpenID Connect 授权、令牌、刷新、撤销和用户信息接口
- 应用、用户、角色、令牌及认证记录管理
- OIDC、LDAP、SAML 外部身份源接入
- MFA（TOTP）与人脸识别认证
- JWT 密钥、回调地址和令牌有效期配置
- 自动数据库迁移、健康检查、OpenAPI 文档和 Prometheus 指标
- MySQL 持久化；未配置 MySQL 时可使用本地 SQLite

## 架构

EAuth 采用前后端分离部署：

```text
浏览器
  │
  ▼
EAuth Console（静态页面 / Nginx）
  │  /api、/public、/face-recognition、/.well-known
  ▼
EAuth Backend :9001
  │
  ▼
MySQL / SQLite
```

本地开发时，前端默认运行在 `8000` 端口并代理到后端 `9001` 端口。生产环境中应由前端 Web 服务器或网关完成相同的反向代理。

## 快速开始

### 环境要求

- Go 1.26.4（以 `go.mod` 为准）
- MySQL 8 或兼容数据库
- Node.js 22+ 与 npm 10+（仅在运行前端时需要）

### 1. 启动 MySQL

```bash
docker run -d \
  --name eauth-mysql \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=EfuCloud \
  -e MYSQL_DATABASE=eauth \
  mysql:8
```

### 2. 配置后端

修改 `config/config.yaml`，至少确认公开访问地址和数据库连接：

```yaml
# 面向用户的前端公开地址，用于生成 OIDC 元数据和回调地址
serverAddress: "http://localhost:8000"
tokenPeriod: 16
uploadPath: "./uploads"

loginConfig:
  faceRecognition: true
  mfa: false

mysql:
  host: "127.0.0.1:3306"
  user: "root"
  password: "EfuCloud"
  dbname: "eauth"
  charset: "utf8mb4"

email:
  smtpServer: "smtp.example.com"
  smtpPort: 465
  username: "noreply@example.com"
  password: "CHANGE_ME"

logConfig:
  production: false
  filename: "./log/eauth.log"
  maxsize: 100
  maxbackups: 7
  maxage: 30
  compress: true
  localtime: true
```

不要将生产环境数据库或邮件凭据提交到 Git。生产部署建议通过 Secret 或外部密钥管理服务注入配置。

### 3. 启动后端

```bash
go run ./cmd/start.go -c ./config/config.yaml
```

服务默认监听 `http://localhost:9001`，启动时会自动迁移数据库并创建默认管理员：

- 用户名：`admin`
- 密码：`EfuCloud`

请在首次登录后立即修改默认密码。

### 4. 启动前端

```bash
git clone https://github.com/efucloud/eauth-console.git
cd eauth-console
npm ci --legacy-peer-deps
npm run start:dev
```

打开 `http://localhost:8000`。

## 服务端点

| 地址                                                         | 说明                             |
| ------------------------------------------------------------ | -------------------------------- |
| `http://localhost:9001/api/health`                           | 健康检查                         |
| `http://localhost:9001/api/info`                             | 构建与运行信息                   |
| `http://localhost:9001/api/v1/swagger.json`                  | OpenAPI 文档                     |
| `http://localhost:9001/api/.well-known/openid-configuration` | 后端 OIDC 元数据接口             |
| `http://localhost:9001/metrics`                              | Prometheus 指标                  |
| `http://localhost:8000/.well-known/openid-configuration`     | 经前端代理公开的 OIDC 元数据地址 |

## 配置说明

服务通过 `-c` / `--config` 参数读取 YAML 文件，默认路径为 `./config/config.yaml`。

| 配置项                        | 说明                                                     |
| ----------------------------- | -------------------------------------------------------- |
| `serverAddress`               | 用户访问系统的前端公开地址，用于生成 OIDC 地址信息       |
| `tokenPeriod`                 | Token 有效期，单位为小时，最小值为 8                     |
| `uploadPath`                  | 上传文件目录；留空时使用当前目录下的 `uploads/`          |
| `loginConfig.mfa`             | 是否启用 MFA                                             |
| `loginConfig.faceRecognition` | 是否启用人脸识别                                         |
| `mysql.*`                     | MySQL 连接配置；省略 `mysql` 时使用当前目录的 `eauth.db` |
| `email.*`                     | SMTP 邮件服务配置                                        |
| `logConfig.*`                 | 日志文件、滚动和输出格式配置                             |

## 开发与验证

```bash
# 格式化
gofmt -w cmd pkg config

# 运行 CI 使用的冒烟测试
go test ./cmd/... ./pkg/config/...

# 构建服务
go build -o ./bin/eauth ./cmd/start.go

# 使用自定义配置运行
./bin/eauth -c ./config/config.yaml
```

项目主要目录：

```text
cmd/              命令行入口和服务启动逻辑
config/           本地配置示例
docs/             Kubernetes 清单与部署文档
generate/         API / TypeScript 代码生成工具
pkg/apis/         HTTP API 与过滤器
pkg/migrations/   数据库迁移
pkg/models/       数据模型与 DTO
pkg/providers/    外部身份源连接器
pkg/services/     业务逻辑
```

## 容器部署

GitHub Actions 会为主分支和版本标签构建多架构镜像：`ghcr.io/efucloud/eauth`。

```bash
docker run --rm \
  -p 9001:9001 \
  -v "$PWD/config/config.yaml:/efucloud/config/config.yaml:ro" \
  -v "$PWD/uploads:/efucloud/uploads" \
  ghcr.io/efucloud/eauth:latest
```

确保配置中的 `uploadPath` 与容器挂载路径一致，例如 `/efucloud/uploads`。

仓库中的 `build.sh` 使用 Docker Buildx 构建并推送镜像，可通过 `IMAGE_REPO`、`IMAGE_TAG`、`PLATFORMS` 和 `DOCKERFILE` 环境变量调整目标。

## Kubernetes 部署

`docs/` 提供 MySQL、后端、前端及 Ingress 的示例清单：

```bash
kubectl apply -f docs/namespace.yaml
kubectl apply -f docs/mysql.yaml
kubectl apply -f docs/backend.yaml
kubectl apply -f docs/frontend.yaml
```

部署前必须替换示例密码、邮件配置、域名、镜像和 TLS 设置。完整说明参见 [`docs/README.md`](./docs/README.md)。

## 许可证

本项目基于 [Apache License 2.0](./LICENSE) 开源。