Marzban 面板安装与首次配置教程（VPS 2026）

Marzban 是伊朗开发者 Gozargah 开源的 Xray 管理面板，核心设计思路是把 Xray 核心、Web 后端、数据库全部容器化。好处是环境隔离干净，升级不怕炸依赖，换 VPS 迁移只需打包挂载目录。代价是安装比 3X-UI 多一个 Docker 环境准备步骤——但你只需要做一次。

这篇文章假设你有一台干净 Ubuntu 22.04 或 24.04 的 VPS（1 核 1 GB 内存起步，2 GB 更稳妥），一个已解析到 VPS IP 的域名。按下面的步骤走完，30 分钟内能拿到一个带 SSL、有 inbound、能生成 Clash 和 sing-box 订阅链接的面板。

装完 Docker 之后，install.sh 到底做了什么？

Marzban 官方安装脚本只有一条命令：

sudo bash -c "$(curl -sL https://github.com/Gozargah/Marzban-scripts/raw/master/marzban.sh)" @ install

这条脚本不编译代码、不装系统依赖，只做三件事：

1. 在当前目录创建 marzban 文件夹，把 docker-compose.yml、.env 模板、xray_config.json 模板复制进去。
2. 创建 /var/lib/marzban 数据目录，用于挂载数据库文件、Xray 配置和模板文件。Docker 容器启动后 SQLite 数据库会存在这个目录的 db.sqlite3 里。
3. 设置目录权限，确保容器内的非 root 用户能读写挂载卷。

如果脚本拉取超时，先确认 VPS DNS、系统时间和 GitHub 连通性；不要把反代镜像接进可执行命令。脚本跑完后不要立即 docker compose up -d——.env 还没改。

.env 里哪些参数不改就没法上线？

cd marzban 进项目目录，用 vim 或 nano 打开 .env。以下 5 个参数必须改，其余可以在后续运维中调整。

参数	默认值	必须改？	说明
UVICORN_PORT	8000	建议改	面板 Web 端口。改完后记得防火墙放行
SUDO_USERNAME	admin	必须改	管理员登录名，默认的太容易被扫
SUDO_PASSWORD	admin	必须改	管理员密码，用 16 位以上带大小写数字
UVICORN_HOST	0.0.0.0	不改	监听所有网卡，如果只在本机反代就留默认
XRAY_JSON	/var/lib/marzban/xray_config.json	不改	Xray 配置文件路径，不用动

数据库默认走 SQLite（SQLALCHEMY_DATABASE_URL = sqlite:////var/lib/marzban/db.sqlite3），单节点够用。多节点部署才需要改成 MySQL 或 MariaDB 连接串——面板 Settings 里有 Inbound 模板同步到节点的机制，但那个是进阶话题，首装不用碰。

改完 .env 保存退出，确认端口没冲突：

ss -tlnp | grep 8000

如果 8000 端口已被占用（比如你之前装过其他面板），改 UVICORN_PORT 为别的值如 8880。

面板跑起来之后，SSL 证书怎么配？

先启动服务：

cd ~/marzban
docker compose up -d

docker compose ps 确认 marzban 和 xray 两个容器都是 Up 状态后，直接 IP:端口访问面板能登录。但 admin/admin 走明文 HTTP 登录，延迟一刻就可能有扫描器撞库。配 SSL 推荐用 Caddy 做一层反代，不仅证书自动续期，而且不依赖 Marzban 重启：

apt install -y caddy

编辑 /etc/caddy/Caddyfile，写入：

你的域名 {
    reverse_proxy 127.0.0.1:8000
}

然后 systemctl reload caddy。Caddy 自动向 Let’s Encrypt 申请证书，前提是你的域名已正确解析到 VPS IP，并且 80/443 端口未被占用。

如果用 Cloudflare DNS 且开了代理（橙色云朵），不需要在 Caddy 或 Nginx 里配证书——Cloudflare 边缘证书已经覆盖了 HTTPS。但这时候 Xray 的 inbound 端口要避开 443，因为 CF 代理不会转发非 HTTP 流量，需要单独开一个高位端口（比如 2083 或 8443）给 inbound 用。

SSL 配好后，回到浏览器访问 https://域名/dashboard/，验证地址栏锁图标为绿色，然后登录改密码。

第一个 Inbound 怎么建？

登录面板，左侧菜单 → Inbounds → Create Inbound。你需要做这几个选择：

协议（Protocol）：VMess 最通用，兼容性最好，所有客户端都支持。VLESS + Reality 的 TLS 指纹更干净，但目前只有 sing-box、Xray-core 和部分 Clash Meta 内核支持。首次测试建议选 VMess + WebSocket，后续再加 Reality 的 inbound。

监听地址：填 0.0.0.0，让 Xray 监听所有网卡。如果只在本机用，填 127.0.0.1。

端口：自选一个未占用的高位端口，如 10086。避开 22、80、443、8000 这类常见端口。设完后记得在 VPS 防火墙放行：

ufw allow 10086/tcp

传输（Network）：TCP 最简单，WebSocket（ws）可以套 CDN，gRPC 适合内网高性能场景。新手选 TCP 就行，创建完后 Inbound 列表里会出现一条绿色 Active 的记录。

这时候 Xray 已经在这个端口上监听了，但没有用户授权谁都不能用。下一步就是把 inbound 绑定到用户。

用户的订阅链接怎么分发？

左侧菜单 → Users → Create User。用户名随意填（如 user01），Status 选 Active，到期天数留空就是永久。关键是 User Inbounds 多选框：勾上你刚创建的 inbound，这个用户就能使用该节点。

创建完用户后，详情页顶部会出现订阅链接：

https://你的域名/sub/user01/

点右侧的 Copy 按钮复制，发给用户。用户在客户端（Clash Verge Rev、Shadowrocket、sing-box、v2rayN）里粘贴这个链接，更新订阅即可拉取节点。

这里有一个容易踩的坑：订阅链接最后的斜杠不能丢。/sub/user01 不带斜杠会返回 404，必须是 /sub/user01/。Marzban 的订阅模块按 REST 风格路由，路径末尾斜杠是区分资源与集合的关键。

面板还支持按用户定制订阅格式——在 User 的 Proxies 设置里，你可以为每个用户单独指定协议标签、伪装域名、传输方式。改完之后客户端重新更新订阅就能拿到新配置，不需要重新分发链接。

Marzban 和 3X-UI 怎么选？

如果你已经在用 3X-UI 而且运行稳定，不一定需要迁移。但如果你刚开 VPS 准备装面板，下面是两者的实际差异。

维度	Marzban	3X-UI
部署方式	Docker（docker-compose）	原生安装脚本（一键 bash）
安装难度	需先装 Docker，多一步	一条命令就跑起来了
Web UI 体验	Vue.js 前端，响应式，交互流畅	经典面板风格，功能全但 UI 较旧
升级方式	docker compose pull && up -d，不影响系统	面板内一键升级或脚本重新拉取
订阅管理	内置订阅模块，支持 Clash/sing-box/V2Ray 格式	有订阅功能但格式支持不如 Marzban 全面
多节点	原生多节点架构，节点独立部署 marzban-node	通过 API 或手动同步配置
REST API	完整的 REST API，适合自动化运维	API 可用但文档较少
数据库	SQLite 默认，可切 MySQL/MariaDB	SQLite + 可切 MySQL
系统侵入性	低，所有依赖在容器内，卸载只需删目录	中，脚本直接操作系统包和二进制文件

核心取舍：如果你熟悉 Docker、有多台 VPS 需要统一管理、想要更好的订阅体验，选 Marzban。如果追求最小安装成本、一台 VPS 跑几个节点就够了、不想学 Docker，3X-UI 更快上手。

常见错误：Docker 没起来、端口冲突、数据库迁移失败

Docker 服务未启动：运行 docker compose 提示 Cannot connect to the Docker daemon。先 systemctl start docker 再 systemctl enable docker 设开机自启。装完 Docker 后没加当前用户到 docker 组也会报权限错误：usermod -aG docker $USER，然后退出 SSH 重连生效。

端口冲突：Marzban 启动后 docker compose logs marzban 显示 Address already in use。Xray 需要的 inbound 端口或面板端口可能被其他进程占用。ss -tlnp | grep 端口号 找冲突进程，kill 掉或换端口。

数据库迁移失败（alembic error）：容器日志出现 alembic 相关报错，通常是旧的 db.sqlite3 和当前镜像版本的数据库 schema 不匹配。先 docker compose down，备份 /var/lib/marzban/db.sqlite3 到别处，删除原文件，再 docker compose up -d 让 Alembic 自动建新表。如果旧数据必须保留，需要在升级前先阅读对应版本的 Release Notes 看是否有 breaking schema change，按迁移指南操作。

面板登录后页面空白：90% 的情况是 Inbound/User 模板文件没放对位置。Marzban 镜像里的默认模板在 /app/app/templates，如果 install.sh 没把这部分复制到 /var/lib/marzban/templates/，创建 inbound 时页面会为空。检查 ls /var/lib/marzban/templates/ 是否有子目录，没有就手动从 GitHub 项目 extra 目录下复制一份。

Marzban 的日常运维比 3X-UI 轻——升级只需 docker compose pull && docker compose up -d，版本回退也只需改 docker-compose.yml 里的镜像 tag 再重启。但前提是第一次安装时把 Docker、.env、SSL、模板这四个基础打扎实。

如果你用的是自己搭的面板而不是机场服务，需要兼容 Clash / Singbox / V2Ray 的订阅来测试你刚配好的 inbound 是否能被客户端正常拉取和连接。

相关阅读

• Hiddify Manager 面板安装与首次配置：VPS 一行命令部署 Reality / Hysteria2 全协议节点（2026）
• 3X-UI 面板安装与首次配置完整教程（VPS 2026）
• Hysteria 2 节点搭建教程：VPS 一键脚本从部署到客户端连接（2026）