Marzban 面板安装与首次配置教程（VPS 2026）
Marzban 用 Docker 容器跑 Xray 核心 + Python Web 后端，安装比 3X-UI 多一步 Docker 环境准备。面板默认 8000 端口，首次登录 admin/admin 后必须立即改密码、配 SSL、创建第一个 inbound 才能上线。本文覆盖从干净 Ubuntu VPS 到 Clash / sing-box 订阅链接分发的完整路径。
操作步骤速查
安装 Docker 和 docker-compose
SSH 登录 VPS，先更新包列表：apt update && apt upgrade -y。然后安装 Docker 官方源：先装依赖 apt install -y ca-certificates curl gnupg lsb-release，添加 Docker GPG 密钥和 apt 源，再 apt install -y docker-ce docker-ce-cli containerd.io。装完用 docker --version 确认版本号出现。docker-compose 在 Docker 24+ 中已内置为 docker compose（注意是空格不是横杠），也可以用 apt install -y docker-compose-plugin 单独装插件。
预期结果：docker --version 返回 Docker version 24.x 或更高版本号，docker compose version 返回 Compose plugin 版本号，sudo systemctl status docker 显示 active (running)。
CentOS 用户可以 yum install -y yum-utils 然后添加 Docker CE 源；推荐用 Docker 官方脚本 curl -fsSL https://get.docker.com | sh 一键安装，但生产环境建议走 apt 源以方便后续更新。
运行 Marzban 官方安装脚本
执行 `sudo bash -c "$(curl -sL https://github.com/Gozargah/Marzban-scripts/raw/master/marzban.sh)" @ install`。脚本会自动在当前目录创建 marzban 文件夹，放入 docker-compose.yml 和 .env 模板文件。注意：脚本不会自动启动服务，只是拉项目文件。如果服务器访问 GitHub 很慢，先停下来检查 DNS 与基础网络，不要把反代镜像直接接到可执行安装命令里。
预期结果：当前目录下出现 marzban 文件夹，用 ls 列出可见 docker-compose.yml 和 .env 两个关键文件。
如果你手动 git clone 拉取项目，extra 目录下的模板文件路径不一样，最后要复制一份到 /var/lib/marzban/templates/。没有面板模板，inbound 的 compose 页面会显示空白。
编辑 .env 配置文件
cd marzban && vim .env 或 nano .env。必改的 4 个参数：UVICORN_PORT=8000（面板端口，按需改）、UVICORN_HOST=0.0.0.0（监听所有网卡）、XRAY_JSON=/var/lib/marzban/xray_config.json（Xray 配置文件路径）、SUDO_USERNAME=admin 和 SUDO_PASSWORD=你设置的强密码。如果需要反代并打开 HTTPS，还需要配 UVICORN_SSL_CERTFILE 和 UVICORN_SSL_KEYFILE 或者用 Nginx/Caddy 在前面反代。数据库默认 SQLite 不用动；多节点部署才需要改成 MySQL 连接串。
预期结果：.env 文件已保存，SUDO_PASSWORD 不再为默认值 admin，UVICORN_PORT 和 XRAY_JSON 等路径参数与实际目录一致。
.env 里任何带 # 注释的行都不要删，Marzban 启动时会解析这些注释判断变量是否被手动设置过。想改某个参数就取消注释并把值改掉，不要新增重复行。
启动 Marzban 容器并登录面板
在 marzban 目录下运行 docker compose up -d。首次启动会从 Docker Hub 拉取 Marzban 和 Xray 镜像，约需 3-5 分钟。拉完后用 docker compose ps 确认 marzban 和 xray 两个容器都是 Up 状态。浏览器访问 http://你VPS的IP:8000/dashboard/，输入设置好的用户名和密码登录。
预期结果：浏览器显示 Marzban 管理后台首页，左侧导航栏包含 Dashboard、Users、Inbounds、Nodes、Settings 等菜单。右上角显示已登录的管理员用户名。
如果你改了 UVICORN_PORT 为非默认值（不是 8000），记得在 VPS 防火墙/安全组中放行该端口。Ubuntu 上 ufw allow 端口号/tcp 即可。另外 Xray 的 inbound 端口也需要在防火墙放行，否则订阅能用但连接会超时。
配置 SSL 证书
Marzban 默认以 HTTP 运行，生产环境必须加 SSL。两种方式：一是在 .env 中设置 UVICORN_SSL_CERTFILE=/path/to/fullchain.pem 和 UVICORN_SSL_KEYFILE=/path/to/privkey.pem，Marzban 内置的 Uvicorn 直接处理 HTTPS；二是在 VPS 上装 Nginx 或 Caddy，用反向代理把 443 端口的 HTTPS 请求转发到 127.0.0.1:8000。推荐第二种方式——Certbot 或 Caddy 可以自动续期 Let's Encrypt 证书，不依赖 Marzban 重启。Caddy 最简单：apt install -y caddy，编辑 /etc/caddy/Caddyfile 写入 `你的域名 { reverse_proxy 127.0.0.1:8000 }`，systemctl reload caddy 即可。
预期结果：浏览器访问 https://你的域名/dashboard/ 显示绿色锁图标，证书有效。Marzban 本身监听 127.0.0.1:8000，外部请求全部通过 Caddy 或 Nginx 转发。
如果你用 Cloudflare DNS，打开 CF 代理（橙色云朵）后 CF 会自动提供边缘证书，VPS 端不需要再配 Let's Encrypt。但要注意 CF 代理模式下 Xray inbound 端口不能走 443，需要单独开一个非标准端口。
创建第一个 Inbound 节点
登录面板后，左侧菜单点 Inbounds → 右上角 Create Inbound。Protocol 选 VMess（最通用）或 VLESS + Reality（TLS 指纹更干净）。Address 填 0.0.0.0，Port 填一个未占用的端口如 10086。Network 选 TCP 或 WebSocket，TLS 可以先不填。填完点 Save。系统会在 xray_config.json 中添加对应的 inbound 配置，Xray 容器自动重载。
预期结果：Inbounds 列表页出现新建的条目，Tag 列显示自动生成的标签名（可在编辑页改成易记的名字如 main-vmess），Status 显示绿色 Active 图标。
协议选 VLESS + Reality 时还需要填一个 SNI（伪装目标域名，如 www.microsoft.com）和生成公私钥对。面板 Inbound 编辑页有 Reality 配置区，点 Generate 自动生成密钥，不用手动 openssl。
创建用户并生成订阅链接
左侧菜单点 Users → Create User。用户名随意（如 user01），Status 选 Active，激活天数按需设置或留空为永久。在 User Inbounds 区域勾选你刚才创建的 inbound。Proxies 页可以给这个用户指定协议标签和伪装参数。保存后，该用户的订阅链接显示在详情页顶部：`https://你的域名/sub/user01/`。User 页面也支持一键复制链接和生成二维码。
预期结果：用户详情页顶部出现订阅链接，右侧有 Copy 按钮和 QR Code 图标。复制链接到浏览器打开，返回 base64 编码的节点列表。粘贴到 Clash Verge Rev 或 Shadowrocket 中能正常拉取节点。
订阅链接最后的斜杠不能丢，否则返回 404。Marzban 也支持在 /sub/user01/all 之类的路径上加参数，具体看 Settings 页的 Subscription 配置。client 端需要勾选 Allow Insecure 时可以在 User 的 Proxies 设置里打开。
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这条脚本不编译代码、不装系统依赖，只做三件事：
- 在当前目录创建
marzban文件夹，把docker-compose.yml、.env模板、xray_config.json模板复制进去。 - 创建
/var/lib/marzban数据目录，用于挂载数据库文件、Xray 配置和模板文件。Docker 容器启动后 SQLite 数据库会存在这个目录的db.sqlite3里。 - 设置目录权限，确保容器内的非 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 -ddocker 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、模板这四个基础打扎实。
如果你用的是自己搭的面板而不是机场服务，需要多格式测试订阅源来测试你刚配好的 inbound 是否能被客户端正常拉取和连接。
相关阅读
常见问题
- Marzban 面板默认用户名和密码是什么？
- 默认用户名 admin、密码 admin。首次登录后立即去设置里修改密码，否则面板暴露在互联网上会被扫到。建议密码长度 16 位以上，包含大小写字母和数字。
- Marzban 能不能和 3X-UI 装在同一台 VPS 上？
- 不建议。Marzban 自带 Xray 核心，3X-UI 也自带了 Xray 二进制，两个进程同时跑会产生端口冲突和路由表混乱。如需迁移，先 docker compose down 停掉 Marzban，再启 3X-UI，反之亦然。
- docker compose 启动后 502 Bad Gateway 怎么排查？
- 502 通常意味着 Nginx/Caddy 反代配了但 Marzban 后端没起来。先跑 docker compose ps 确认所有容器状态为 Up；如果 marzban 容器反复重启，用 docker compose logs marzban 看后端日志，常见原因是 .env 配置错误或端口被其他进程占用。
- Marzban 生成的订阅链接格式是什么？
- 订阅链接格式为 https://你的域名/sub/用户token/，最后带斜杠。用户端在 Clash、sing-box 或 Shadowrocket 中粘贴这个链接即可拉取节点。面板支持按用户 token 区分订阅内容，修改用户 inbound 后客户端更新订阅就能拿到新节点。
- 数据库迁移失败（alembic error）怎么处理？
- 迁移失败最常见原因是旧的 SQLite 数据库文件和当前 Marzban 镜像版本不匹配。停掉容器后先备份 /var/lib/marzban/db.sqlite3，删除数据库文件，重启容器让 Alembic 自动创建新表结构。旧数据需手动导出导入。
来源与时间
本文最后查看时间：2026-04-15。操作路径会随客户端版本变化，遇到按钮名称不一致时，优先按同义菜单和官方文档查看。