部署准备与安装
准备 MCP HTTPS 地址、可写持久化目录，以及独立保存的配置加密密钥。远程管理另外配置管理员 HTTPS origin，并在本机初始化管理员账号。网关保持单活；PostgreSQL 不提供 Hub 多实例运行时协调。
| 模式 | 适用场景 | 入口 |
|---|---|---|
| 本地管理 + SQLite | 在网关所在机器开发或维护 | 下方最小配置，内建账号登录，只绑定回环 |
| 远程管理 + SQLite / PostgreSQL | 团队使用、审批与集中管理 | 部署指南，独立管理员登录和 HTTPS |
| YAML 管理 | 不启用控制台、仅发布明确只读的工具 | 高级纯 YAML 示例 |
运行网关的机器安装 mcphub；用户电脑安装 mcpbridge。管理员使用管理 CLI 时也需安装后者。服务端下载：
| 平台 | 服务端下载 |
|---|---|
| macOS Intel | mcphub_v2.4.0_darwin_amd64.tar.gz |
| macOS Apple Silicon | mcphub_v2.4.0_darwin_arm64.tar.gz |
| Linux amd64 | mcphub_v2.4.0_linux_amd64.tar.gz |
| Linux arm64 | mcphub_v2.4.0_linux_arm64.tar.gz |
从 v2.4.0 发行页面 下载服务端包和 SHA256SUMS，核对校验值后解压。以下为 Linux arm64 的安装示例；按上表替换文件名，macOS 校验命令为 shasum -a 256：
sha256sum mcphub_v2.4.0_linux_arm64.tar.gz
# 与 SHA256SUMS 中同名条目逐字核对，一致后再解压。
mkdir -p mcphub-release "$HOME/.local/bin"
tar -xzf mcphub_v2.4.0_linux_arm64.tar.gz -C mcphub-release
install -m 755 mcphub-release/mcphub "$HOME/.local/bin/mcphub"
export PATH="$HOME/.local/bin:$PATH"
安装后运行 mcphub --version，应显示 mcphub 2.4.0 (server)。validate、serve 是服务端命令；mcpbridge 是用户连接器，供用户连接 Agent，不能启动或校验网关。源码更新不会自动替换目录里的旧二进制；要使用刚安装的程序路径。
此 PATH 设置用于当前终端；后续可直接运行 "$HOME/.local/bin/mcphub"，或将工具目录加入服务环境。已安装 Go 1.26.8 时也可执行：
go install github.com/SamuelSupe/mcphub/v2/cmd/mcphub@v2.4.0
Go 安装路径是 go env GOBIN，为空时是 $(go env GOPATH)/bin；该目录也需要加入 PATH。
v2.4.0 服务端包与指南包含相同模板。 默认 config.example.yaml 启用本地管理台、SQLite 和 backends: []，只需要网关地址和配置加密密钥。启动管理台后，逐个添加服务，分别填写凭证、测试连接，再发布已审核的工具并配置权限。团队远程管理使用远程模板；不启用控制台时选择独立的高级纯 YAML 示例。
validate --config PATH 校验配置，不创建 SQLite 数据库；serve --config PATH 初始化新数据库并启动服务，JSON 日志写到 stderr。
部署前先查示例选择与配置生效方式、环境变量/Secret 写法和部署变量清单。不要把所有可选模块同时塞进基础配置。
本地管理 UI
默认模板启用内建账号、本地管理台、SQLite、个人授权中心和 backends: []。管理台只监听网关机器的 127.0.0.1:8081，仍须账号登录。远程访问使用远程模板和 HTTPS。
复制包内模板，在新部署目录中配置公开地址和固定密钥：
cp mcphub-release/config.example.yaml config.yaml
export MCPHUB_PUBLIC_URL=https://hub.example.com/mcp
umask 077
mkdir -p secrets
test -f secrets/config.key || openssl rand -base64 32 > secrets/config.key
export MCPHUB_CONFIG_KEY="$(cat secrets/config.key)"
mcphub validate --config config.yaml
mcphub serve --config config.yaml
在服务器本机的另一个终端进入同一目录，加载相同的两个变量，初始化管理员：
export MCPHUB_PUBLIC_URL=https://hub.example.com/mcp
export MCPHUB_CONFIG_KEY="$(cat secrets/config.key)"
mcphub init-admin --config config.yaml --username admin
密码在终端隐藏输入，至少 12 个字符；没有默认密码，也没有匿名网页初始化接口。打开本地管理台，登录后在「用户与组」创建用户和组、配置组权限并维护成员关系，再按 添加后端 → 测试连接 → 发布工具 接入服务。
默认只要求公开地址和配置密钥，不设置 MCPHUB_AUTH_ISSUER 或固定后端变量。密钥是 Base64 编码的 32 字节，只生成一次，重启时使用同一私有文件；服务管理器也必须注入这两个变量，MCPHub 不自动加载 .env。数据库在 YAML 文件旁的 data/mcphub.db。
内建签发者由公开 origin 推导到 /sso。空后端新部署的 /readyz 可返回 200，不依赖外部 OIDC。就绪不证明公开 HTTPS 或业务后端已验收。MCPBridge 与远程用户需要公开 HTTPS、OAuth 元数据和用户门户路由可达。密码、停用、MFA 与本机恢复见内建账号。
远程管理员与 PostgreSQL
支持独立管理员登录、远程 UI/API、mcpbridge admin 与按管理员身份记录的配置审计。管理员 JWT 使用 admin.public_url 作为 audience，且必须具有 admin.required_scopes（默认 mcphub:admin）；普通 MCP 用户的登录凭证不会自动获得管理权限。
mcpbridge login --admin --server https://admin.example.com --client-id mcpbridge-admin --profile ops
mcpbridge admin --profile ops get /overview
mcpbridge admin --profile ops get /backends
mcpbridge admin --profile ops get /tool-groups
mcpbridge admin --profile ops get /events
数据库可选 SQLite（默认）或 PostgreSQL（database_driver: postgres 与 database_dsn_env）。本版支持单实例网关；PostgreSQL 不代表已支持多实例运行时同步。完整的账号初始化、可选 OIDC 注册、浏览器登录、API 写入、数据库与 HTTPS 代理部署见 部署指南。