Skip to content

Commit 64d8d77

Browse files
whatwewantwhatwewant
committed
docs: add VitePress documentation site and GitHub Pages workflow
Add docs/ with TypeScript, VitePress, and pnpm: guides (intro through Docker), examples for OAuth modes and upstream, detailed YAML configuration reference, and Deploy Docs workflow with VITEPRESS_BASE=/connect/ for project Pages. Made-with: Cursor
1 parent 781c98a commit 64d8d77

21 files changed

Lines changed: 2768 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- main
8+
paths:
9+
- 'docs/**'
10+
- '.github/workflows/docs.yml'
11+
workflow_dispatch:
12+
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
concurrency:
19+
group: pages
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
31+
- name: Setup pnpm
32+
uses: pnpm/action-setup@v4
33+
with:
34+
version: 9
35+
36+
- name: Setup Node.js
37+
uses: actions/setup-node@v4
38+
with:
39+
node-version: '20'
40+
cache: 'pnpm'
41+
cache-dependency-path: docs/pnpm-lock.yaml
42+
43+
- name: Install dependencies
44+
run: |
45+
cd docs
46+
pnpm install --frozen-lockfile
47+
48+
- name: Build
49+
env:
50+
VITEPRESS_BASE: /connect/
51+
run: |
52+
cd docs
53+
pnpm run build
54+
55+
- name: Setup Pages
56+
uses: actions/configure-pages@v4
57+
58+
- name: Upload artifact
59+
uses: actions/upload-pages-artifact@v3
60+
with:
61+
path: docs/.vitepress/dist
62+
63+
deploy:
64+
environment:
65+
name: github-pages
66+
url: ${{ steps.deployment.outputs.page_url }}
67+
runs-on: ubuntu-latest
68+
needs: build
69+
steps:
70+
- name: Deploy to GitHub Pages
71+
id: deployment
72+
uses: actions/deploy-pages@v4

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
.vitepress/cache
3+
.vitepress/dist

‎docs/.vitepress/config.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// 本地开发默认为 '/'。部署到 GitHub Pages 项目页时 CI 会设置 VITEPRESS_BASE=/connect/
4+
const base = process.env.VITEPRESS_BASE ?? '/'
5+
6+
export default defineConfig({
7+
base,
8+
lang: 'zh-CN',
9+
title: 'GoZoox Connect',
10+
description:
11+
'轻量、强大的认证连接器（Auth Connect），支持 OAuth2、Doreamon、GitHub、飞书等。',
12+
cleanUrls: false,
13+
themeConfig: {
14+
logo: '/logo.svg',
15+
nav: [
16+
{ text: '指南', link: '/guide/introduction', activeMatch: '^/guide/' },
17+
{ text: '示例', link: '/examples/', activeMatch: '^/examples/' },
18+
{ text: 'GitHub', link: 'https://github.com/go-zoox/connect' }
19+
],
20+
sidebar: {
21+
'/guide/': [
22+
{
23+
text: '入门',
24+
items: [
25+
{ text: '简介', link: '/guide/introduction' },
26+
{ text: '安装', link: '/guide/installation' },
27+
{ text: '快速开始', link: '/guide/quick-start' },
28+
{ text: '部署形态', link: '/guide/architecture' }
29+
]
30+
},
31+
{
32+
text: '使用手册',
33+
items: [
34+
{ text: '命令行', link: '/guide/cli' },
35+
{ text: '配置', link: '/guide/config' },
36+
{ text: 'Docker 与编排', link: '/guide/docker' }
37+
]
38+
}
39+
],
40+
'/examples/': [
41+
{
42+
text: '示例',
43+
items: [
44+
{ text: '概览', link: '/examples/' },
45+
{ text: 'Doreamon 模式', link: '/examples/doreamon' },
46+
{ text: 'GitHub OAuth', link: '/examples/github' },
47+
{ text: '飞书 OAuth', link: '/examples/feishu' },
48+
{ text: '上游代理（单站点）', link: '/examples/upstream' },
49+
{ text: '无认证穿透', link: '/examples/none' }
50+
]
51+
}
52+
]
53+
},
54+
socialLinks: [{ icon: 'github', link: 'https://github.com/go-zoox/connect' }],
55+
footer: {
56+
message: '基于 MIT 许可证发布',
57+
copyright: 'Copyright © GoZoox'
58+
},
59+
search: { provider: 'local' },
60+
outline: { level: [2, 3] }
61+
}
62+
})

‎docs/examples/doreamon.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Doreamon 模式
2+
3+
适合已开通 **Doreamon**（或兼容同一 OAuth 契约的服务）的应用：`oauth2[].name` 为 `doreamon`，回调形如 `/login/doreamon/callback`。
4+
5+
## 环境变量启动
6+
7+
```bash
8+
export SECRET_KEY=$(openssl rand -hex 16)
9+
export UPSTREAM=https://your-demo-site.example.com
10+
11+
export CLIENT_ID=<CLIENT_ID>
12+
export CLIENT_SECRET=<CLIENT_SECRET>
13+
export REDIRECT_URI=https://connect.example.com/login/doreamon/callback
14+
15+
connect doreamon
16+
```
17+
18+
若不用 `UPSTREAM`，可同时指定：
19+
20+
```bash
21+
export FRONTEND=http://127.0.0.1:8000
22+
export BACKEND=http://127.0.0.1:8001
23+
```
24+
25+
## Docker Compose 片段
26+
27+
```yaml
28+
services:
29+
connect:
30+
image: whatwewant/connect-doreamon:v1
31+
ports:
32+
- '8080:8080'
33+
environment:
34+
SECRET_KEY: ${SECRET_KEY}
35+
UPSTREAM: ${UPSTREAM}
36+
CLIENT_ID: ${CLIENT_ID}
37+
CLIENT_SECRET: ${CLIENT_SECRET}
38+
REDIRECT_URI: ${REDIRECT_URI}
39+
```
40+
41+
## IdP 侧检查清单
42+
43+
- Redirect URI 与 `REDIRECT_URI` 完全一致（协议、端口、路径）。
44+
- Client ID / Secret 与 Connect 环境变量一致。
45+
- 生产环境使用 HTTPS，并与会话 Cookie 策略一致。

‎docs/examples/feishu.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# 飞书 OAuth
2+
3+
飞书开放平台创建应用后，拿到 App ID / App Secret，回调一般为 `/login/feishu/callback`（与配置的 `oauth2[].name` 一致）。
4+
5+
## CLI
6+
7+
```bash
8+
export SECRET_KEY=$(openssl rand -hex 16)
9+
export UPSTREAM=https://your-internal-gateway.example.com
10+
11+
export CLIENT_ID=<FEISHU_APP_ID>
12+
export CLIENT_SECRET=<FEISHU_APP_SECRET>
13+
export REDIRECT_URI=https://connect.example.com/login/feishu/callback
14+
15+
connect feishu
16+
```
17+
18+
## 注意事项
19+
20+
- 飞书侧「重定向 URL」需与白名单一致。
21+
- 与其它 OAuth 模式相同：必须提供 **`UPSTREAM`** 或 **`FRONTEND`+`BACKEND`**。
22+
23+
更细的 Scope、租户开通流程请参阅 [飞书开放平台文档](https://open.feishu.cn/)（外链可能变更，以官网为准）。

‎docs/examples/github.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# GitHub OAuth
2+
3+
使用 GitHub OAuth App 作为登录提供方：`auth.provider` 为 `github`，回调路径 `/login/github/callback`。
4+
5+
## CLI
6+
7+
```bash
8+
export SECRET_KEY=$(openssl rand -hex 16)
9+
export UPSTREAM=https://httpbin.zcorky.com
10+
11+
export CLIENT_ID=<GITHUB_APP_CLIENT_ID>
12+
export CLIENT_SECRET=<GITHUB_APP_CLIENT_SECRET>
13+
export REDIRECT_URI=http://127.0.0.1:8080/login/github/callback
14+
15+
connect github
16+
```
17+
18+
## GitHub 控制台配置要点
19+
20+
1. Authorization callback URL 填写与 `REDIRECT_URI` 相同。
21+
2. 若仅允许部分 GitHub 用户，可在配置里设置 **`auth.allow_usernames`**（参见 [配置](../guide/config.md)）。
22+
23+
## YAML 片段
24+
25+
参考 `conf/config.oauth.yml.example`，将 `oauth2` 中 `name` 改为 `github` 并填入 GitHub 发放的 Client ID/Secret。
26+
27+
```yaml
28+
oauth2:
29+
- name: github
30+
client_id: ${GITHUB_CLIENT_ID}
31+
client_secret: ${GITHUB_CLIENT_SECRET}
32+
redirect_uri: https://connect.example.com/login/github/callback
33+
```

‎docs/examples/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# 示例概览
2+
3+
以下为可复制粘贴的起点；生产环境请替换密钥、域名与回调 URL。
4+
5+
| 示例 | 场景 |
6+
|------|------|
7+
| [Doreamon](./doreamon) | 使用 Doreamon IdP，OAuth + 上游 |
8+
| [GitHub](./github) | GitHub OAuth App |
9+
| [飞书](./feishu) | 飞书开放平台 OAuth |
10+
| [上游代理](./upstream) | 单一 `upstream`，YAML 最小集 |
11+
| [无认证](./none) | `connect none`，纯转发 |
12+
13+
完整字段说明仍以 [配置](../guide/config.md) 与源码为准。

‎docs/examples/none.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# 无认证穿透
2+
3+
`auth.mode` 为 **`none`** 时不挂载 OAuth /登录中间件，只做反向代理，适用于：
4+
5+
- 上游已有网关鉴权；
6+
- 内网调试；
7+
- 临时暴露静态站点。
8+
9+
## CLI
10+
11+
```bash
12+
export UPSTREAM=http://127.0.0.1:3000
13+
# 或使用 FRONTEND + BACKEND
14+
15+
connect none
16+
```
17+
18+
同样必须满足：**upstream** 或 **frontend + backend** 其一。
19+
20+
## 风险提示
21+
22+
无认证模式不会对访客做强校验，请勿直接暴露在公网敏感资产前。

‎docs/examples/upstream.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# 上游代理（单站点）
2+
3+
仅代理到一个 HTTP(S) 上游时，使用 **`upstream`** 块或环境变量 **`UPSTREAM`**。
4+
5+
## YAML 最小示例
6+
7+
对应仓库 `conf/config.upstream.yml.example`：
8+
9+
```yaml
10+
port: 8080
11+
secret_key: go-zoox
12+
session_max_age: 86400
13+
14+
upstream:
15+
host: 127.0.0.1
16+
port: 8000
17+
18+
oauth2:
19+
- name: doreamon
20+
client_id: <CLIENT_ID>
21+
client_secret: <CLIENT_SECRET>
22+
redirect_uri: http://127.0.0.1:8080/login/doreamon/callback
23+
```
24+
25+
启动：
26+
27+
```bash
28+
connect serve -c ./conf/config.upstream.yml
29+
```
30+
31+
## 环境变量等价写法
32+
33+
```bash
34+
export UPSTREAM=http://127.0.0.1:8000
35+
export CLIENT_ID=...
36+
export CLIENT_SECRET=...
37+
export REDIRECT_URI=http://127.0.0.1:8080/login/doreamon/callback
38+
39+
connect doreamon
40+
```
41+
42+
区别：YAML 可同时声明多条 `oauth2`、自定义 `routes`；纯 env 适合容器注入。

‎docs/guide/architecture.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# 部署形态
2+
3+
Connect 向外暴露一个 HTTP 服务（默认 `:8080`），向内则有两种典型接法。
4+
5+
## 形态 A：单一 Upstream
6+
7+
只配置 **upstream**：所有（通过鉴权后的）请求按路径转发到同一目标（协议 + 主机 + 端口）。
8+
9+
适用于：
10+
11+
- 单体站点、静态 + API 同源的反向代理；
12+
- 已有网关后面的单一 origin。
13+
14+
配置示例见仓库 `conf/config.upstream.yml.example` 与 [示例：上游代理](/examples/upstream)。
15+
16+
YAML 中与 upstream 相关的键为 `upstream.host` / `upstream.port` / `upstream.protocol`（或通过环境变量 `UPSTREAM` 一次性注入 URL）。
17+
18+
## 形态 B：Frontend + Backend
19+
20+
同时配置 **frontend** 与 **backend**：
21+
22+
- **frontend**：一般为静态资源或 SPA 所在地址；
23+
- **backend**：API 服务；默认会以 `/api` 等为前缀做路由与重写（可用配置关闭前缀重写）。
24+
25+
适用于前后端分离、静态与 API 域名或端口不一致的情况。
26+
27+
参考 `conf/config.oauth.yml.example`、`conf/config.full.example`。
28+
29+
## 与环境变量的关系
30+
31+
子命令 `doreamon` / `github` / `feishu` / `none` 会在内存中生成一份 `Config`，等价于手写 YAML 的一部分；你也可以始终使用 `connect serve -c file.yml` 完全显式控制。
32+
33+
无论哪种形态，OAuth 回调路径通常为：
34+
35+
```txt
36+
http(s)://<connect-host>:<port>/login/<oauth2-name>/callback
37+
```
38+
39+
`<oauth2-name>` 与配置里 `oauth2[].name` 一致（如 `doreamon`、`github`、`feishu`）。
40+
41+
## 会话与安全
42+
43+
生产环境务必设置稳定的 `secret_key`，并通过 HTTPS + 正确的 `redirect_uri` 注册到 IdP。关于 Cookie `Secure` 与 `SESSION_SECURE` 等行为，以运行时配置为准（参见源码中 `ApplyDefault` 与 OAuth 中间件）。

0 commit comments

Comments
 (0)