Skip to content

配置 ​

Connect 使用 YAML,通过 github.com/go-zoox/config 映射到 app/config.Config。命令行入口一般为:

bash
connect serve -c /absolute/or/relative/path/config.yml

加载完成后仍会执行 Config.ApplyDefault():缺失字段会被补上默认值;与环境变量合并时,常见做法是 先有 YAML,再用 env 覆盖(详见文末「环境变量」)。


仓库里的示例文件 ​

文件用途
conf/config.full.exampleOAuth2 + 前后端 + password + services + routes
conf/config.oauth.yml.exampleOAuth2 + 前后端
conf/config.upstream.yml.example单一 upstream + OAuth2
conf/config.local.yml.example本地密码登录 + services 全 local

下列字段名均来自源码中的 config:"..." 标签;YAML 中请使用 snake_case(与 Go 结构体标签一致)。


顶层字段 ​

字段类型说明
portintHTTP 监听端口;默认 8080,可被环境变量 PORT 覆盖
modestringdevelopment / production;影响静态资源、Cookie 策略等
secret_keystringSession 加密密钥;生产环境必填稳定值;可被 SECRET_KEY 覆盖
session_max_ageint会话有效期,单位为秒(例如一天为 86400);默认约一天量级
log_levelstring日志级别;可被 LOG_LEVEL 覆盖
loading_htmlstring加载页 HTML(可选)
index_htmlstring首页 HTML(可选)

session_max_age 常见误区

若误填成毫秒级大数(如 86400000 当作「一天」),会话会过长。请确认单位为 秒。


Upstream(单上游) ​

与 frontend/backend 互斥使用:要么只配 upstream,要么配 frontend + backend。

字段说明
protocolhttp 或 https;省略时后续逻辑会补默认
host主机名或 IP
port端口;http 默认 80、https 默认 443(见 UpstreamService.String())
change_origin是否改写 Origin(按部署需求)

等价环境变量: UPSTREAM(完整 URL,如 https://httpbin.zcorky.com)。

YAML 键名必须是 protocol,不要使用 scheme。


Frontend / Backend(前后端分离) ​

节点字段说明
frontendprotocol, host, port, change_origin静态或 SPA 所在地址
backend同上API 服务地址
backendprefix后端 API 路径前缀,默认 /api
backendis_disable_prefix_rewrite是否关闭前缀重写

等价环境变量:FRONTEND、BACKEND(均为完整 URL)。


认证:auth ​

字段说明
modeoauth2、password、none、openid 等
provider使用哪一条 oauth2[].name(例如 doreamon、github、feishu、slack)
ignore_paths不需要登录的路径前缀列表
is_ignore_paths_disabled为 true 时忽略上述列表(全部需登录)
is_ignore_when_header_authorization_found已有 Authorization 头时可跳过部分鉴权逻辑
allow_usernames仅允许列表中的用户名登录(如收紧 GitHub 登录用户)

可被 AUTH_MODE、AUTH_PROVIDER、AUTH_IGNORE_PATHS 等覆盖。


OAuth2:oauth2 ​

数组;每条对应一种 IdP,登录回调路径一般为:

txt
http(s)://<connect-host>:<port>/login/<name>/callback
字段说明
name与 auth.provider 对应;同时也是 URL 中的 <name>
client_id / client_secretIdP 发放的凭证
redirect_uri必须与 IdP 控制台注册完全一致
scope可选;依 IdP 要求填写(如 Slack 逗号分隔 scope)

可同时配置多条(例如同时声明 doreamon 与 slack,再通过 auth.provider 选用当前生效的一条)。


密码登录:password ​

字段说明
modelocal:内置列表;service:远程 HTTP 校验
local数组,每项含 username、password
service远程校验 URL(POST)

当 auth.mode 为 password 时使用。


内置业务数据:services ​

内置 HTTP API(如应用信息、当前用户、菜单等)的数据来源可以是远端 HTTP(service)或写死在配置里的 local。

键含义
services.app应用元数据
services.user当前用户
services.menus菜单树
services.permissions权限列表
services.users用户列表(结构同菜单项数组场景见源码)
services.open_idOpenID 相关信息

每个服务常见子字段:

子字段说明
modeservice 或 local
serviceGET 拉取数据的 URL(依具体 API 约定)
local直接写在 YAML 里的对象或数组

未在 YAML 中填写时,ApplyDefault() 会为 Doreamon 生态补上默认的 api.zcorky.com 系列地址(可在自有部署中整体替换)。

请求路径上的查询与缓存 ​

services.user / services.permissions / services.menus / services.open_id 的结果会按 token / email 缓存在进程内(默认 memory,TTL 取 session_max_age)。排障时要知道:

  • X-Connect-Token 里的 permissions 从哪来:优先用 user 服务返回的 result.permissions;为空时才回查 services.permissions,而这条回查发生在每一个代理请求上。所以账号 permissions 为空 + services.permissions 不可用时,表现为「只有这个账号每个请求都慢」。
  • 查询失败也会被缓存 30 秒(负缓存):权限服务挂掉时,最多每个 token 每 30 秒付一次外部查询,而不是每个请求一次。
  • services.open_id 只在会话来自 OAuth2 登录时才解析(需要 provider 的 client 凭据),没有 provider 直接跳过,不再在请求路径上阻塞。
  • 请求路径上没有任何 time.Sleep 限流:慢请求请查上面几条查询,而不是等固定几秒。

常用降延迟手段:services.permissions.mode: local(或把 service 指向真正可用的端点)、services.open_id.mode: local。


自定义路由:routes ​

将某路径前缀转发到指定后端主机(常用于微服务网关场景)。

路径字段说明
routes[].path匹配的前缀
routes[].backend.service_protocol如 https
routes[].backend.service_name主机名
routes[].backend.service_port端口
routes[].backend.disable_rewrite是否禁用重写
routes[].backend.secret_key可选;路由级密钥

示例:

yaml
routes:
  - path: /api/ms/httpbin
    backend:
      service_protocol: https
      service_name: httpbin.zcorky.com
      service_port: 443

键名大小写

请使用 snake_case(如上)。若仓库中旧示例曾出现 camelCase,请以源码 config 标签为准。


内置 API 路径:built_in_apis ​

控制 /api 下各 JSON 端点的路径后缀(非主机名)。

字段默认(摘自 ApplyDefault)
app/app
user/user
menus/menus
permissions/permissions
users/users
config/config
qrcode/qrcode
login/login
built_in(源码字段 Public)/_

也可用环境变量 BUILT_IN_APIS_APP、BUILT_IN_APIS_USER 等单独覆盖。


菜单项:menus.local 等结构 ​

单条菜单常见字段(对应 MenuItem):

字段说明
id可选
name展示名称
path前端路径
icon图标标识
sort排序
hidden是否隐藏(YAML 键名为 hidden)
expanded是否默认展开
layout布局
iframe内嵌 iframe 地址
redirect重定向

完整示例一:单一 upstream + 多条 OAuth2 ​

适合:反向代理一个站点,并在多条 IdP 之间切换(通过 auth.provider)。

yaml
port: 8080

secret_key: REPLACE_WITH_LONG_RANDOM_STRING

session_max_age: 86400

upstream:
  protocol: https
  host: httpbin.zcorky.com
  port: 443

oauth2:
  - name: doreamon
    client_id: <DOREAMON_CLIENT_ID>
    client_secret: <DOREAMON_CLIENT_SECRET>
    redirect_uri: http://127.0.0.1:8080/login/doreamon/callback

  - name: slack
    client_id: <SLACK_CLIENT_ID>
    client_secret: <SLACK_CLIENT_SECRET>
    redirect_uri: https://connect.example.com/login/slack/callback
    scope: identity.basic,identity.email,identity.avatar

auth:
  mode: oauth2
  provider: slack   # 当前登录使用 oauth2 名称为 slack 的这一条

完整示例二:前后端 + OAuth2 + password + services + routes ​

与 conf/config.full.example 同级复杂度(占位 URL 请替换为真实环境)。

yaml
port: 8080

secret_key: go-zoox

session_max_age: 86400

frontend:
  protocol: http
  host: 127.0.0.1
  port: 8000

backend:
  protocol: http
  host: 127.0.0.1
  port: 8001
  prefix: /api
  is_disable_prefix_rewrite: false

oauth2:
  - name: doreamon
    client_id: <CLIENT_ID>
    client_secret: <CLIENT_SECRET>
    redirect_uri: http://127.0.0.1:8080/login/doreamon/callback

password:
  mode: local
  local:
    - username: admin
      password: admin
  service: https://api.example.com # auth.mode=password 且 mode=service 时使用

auth:
  mode: oauth2
  provider: doreamon

services:
  app:
    mode: service
    local:
      name: Lighthouse DNS
      logo: https://avatars.githubusercontent.com/u/7463687?v=4
      description: 轻量级 DNS 服务
    service: https://api.example.com/oauth/app

  user:
    mode: service
    local:
      id: '0x01'
      username: admin
      nickname: 管理员
      avatar: https://avatars.githubusercontent.com/u/7463687?v=4
      permissions:
        - /s/dns
        - /s/docker
    service: https://api.example.com/user

  menus:
    mode: service
    local:
      - name: Home
        path: /i
        icon: appstore
      - name: DNS 管理
        path: /i/dns
        icon: appstore
        layout: header
    service: https://api.example.com/menus

  users:
    mode: service
    service: https://api.example.com/users

  open_id:
    mode: service
    service: https://api.example.com/oauth/app/user/open_id

routes:
  - path: /api/ms/httpbin
    backend:
      service_protocol: https
      service_name: httpbin.zcorky.com
      service_port: 443

完整示例三:密码登录 + 全部 local services ​

适合离线演示或与 conf/config.local.yml.example 对照。

yaml
port: 8080

secret_key: go-zoox

frontend:
  protocol: http
  host: 127.0.0.1
  port: 8000

backend:
  protocol: http
  host: 127.0.0.1
  port: 8001

password:
  mode: local
  local:
    - username: admin
      password: admin

auth:
  mode: password

services:
  app:
    mode: local
    local:
      name: Lighthouse DNS
      logo: https://avatars.githubusercontent.com/u/7463687?v=4
      description: 轻量级 DNS 服务

  user:
    mode: local
    local:
      id: '0x01'
      username: admin
      nickname: 管理员
      avatar: https://avatars.githubusercontent.com/u/7463687?v=4
      permissions:
        - /s/dns
        - /s/docker

  menus:
    mode: local
    local:
      - name: Home
        path: /i
        icon: appstore
      - name: DNS 管理
        path: /i/dns
        icon: appstore
        layout: header

环境变量与 YAML ​

以下变量在 ApplyDefault() 中最常被读取;若同时存在于 YAML,一般以 环境变量覆盖内存中的配置 为准(具体顺序以实现为准,建议:敏感信息走 env,结构走 YAML)。

变量作用
PORT端口
MODE运行模式
SECRET_KEY会话密钥
SESSION_MAX_AGE会话时长(秒)
LOG_LEVEL日志
UPSTREAM单上游 URL
FRONTEND / BACKEND前后端 URL
AUTH_*认证模式、忽略路径等
BUILT_IN_APIS_*内置 API 路径前缀

更全列表见 命令行。


延伸阅读 ​

基于 MIT 许可证发布