星河避难所

返回

生产部署

本文介绍如何将 OneAdmin 部署到生产环境，包含构建策略、运行方式、反向代理及 Docker 部署方案。

查看更多

构建生产版本#

建议在本地完成构建后再上传到服务器，而不是在服务器上直接构建。

原因：

  • 构建过程依赖 Node.js（前端编译）
  • 服务器通常不具备完整前端构建环境
  • 可避免生产环境依赖污染与构建不一致问题

本地构建#

make build
bash

构建完成后生成：

./bin/oneadmin
bash

该二进制文件已包含：

  • 后端 API 服务
  • 前端构建资源（已嵌入，无需额外部署）

上传到服务器#

建议目录结构：

/opt/oneadmin/
├── oneadmin        # 可执行文件
├── config.yaml     # 配置文件
└── logs/           # 日志目录（运行时生成）
text

上传示例：

scp ./bin/oneadmin user@server:/opt/oneadmin/
scp ./config.yaml user@server:/opt/oneadmin/
bash

文件权限说明（重要）#

运行过程中会写入日志目录，例如：

logs/
text

请确保运行用户具备写权限：

mkdir -p /opt/oneadmin/logs
chown -R www-data:www-data /opt/oneadmin
chmod -R 755 /opt/oneadmin
bash

否则可能导致：

  • 日志写入失败
  • 服务异常退出

运行服务#

GIN_MODE=release ./oneadmin -config ./config.yaml -port 9000
bash

生产环境必须设置 GIN_MODE=release，否则将运行在 debug 模式。

使用 systemd 管理服务（推荐）#

创建服务文件#

sudo vim /etc/systemd/system/oneadmin.service
bash
[Unit]
Description=OneAdmin Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/oneadmin
Environment="GIN_MODE=release"
ExecStart=/opt/oneadmin/oneadmin -config /opt/oneadmin/config.yaml -port 9000
Restart=always
RestartSec=5
User=www-data

[Install]
WantedBy=multi-user.target
text

启动服务#

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable oneadmin
sudo systemctl start oneadmin
bash

查看状态与日志#

sudo systemctl status oneadmin
journalctl -u oneadmin -f
bash

配置 Nginx 反向代理（推荐）#

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
text

启用配置：

sudo nginx -t
sudo systemctl reload nginx
bash

访问服务#

部署完成后：

Docker 部署（可选）#

思路说明#

推荐方式：

本地构建二进制 → 上传到服务器 → 挂载目录运行

该方式无需构建镜像，部署简单，更新高效。

目录结构#

/opt/oneadmin/
├── oneadmin
├── config.yaml
└── logs/
text

权限设置#

# 添加执行权限
chmod +x /opt/oneadmin/oneadmin

# 创建日志目录
mkdir -p /opt/oneadmin/logs

# 设置目录权限
chmod -R 755 /opt/oneadmin
bash

启动容器#

docker run -d \
    -p 9000:9000 \
    -e GIN_MODE=release \
    -v /opt/oneadmin:/app \
    --name oneadmin \
    alpine:latest \
    /app/oneadmin -config /app/config.yaml -port 9000
bash

参数说明：

  • -d​：以后台模式运行容器（detached），不会占用当前终端
  • -p 9000:9000​：端口映射
    将宿主机的 9000 端口映射到容器内的 9000 端口
  • -e GIN_MODE=release：设置环境变量
    启用 Gin 的生产模式，关闭调试日志，提高性能
  • -v /opt/oneadmin:/app​：挂载目录（数据卷）
    将宿主机 /opt/oneadmin​ 目录挂载到容器内 /app
    用于：
    • 存放配置文件（config.yaml）
    • 持久化日志（logs）
    • 放置编译后的程序（oneadmin）
  • -w /app​：设置容器工作目录（关键参数）
    指定容器启动时的当前工作目录为 /app​
    这样程序中使用相对路径（如 config.yaml）时才会正确解析
  • --name oneadmin​：指定容器名称
    方便后续使用 docker stop / start / logs 等命令管理容器
  • alpine:latest：使用的基础镜像
    一个轻量级的 Linux 发行版，适合运行 Go 编译后的二进制程序
  • ./oneadmin：容器启动后执行的程序
    即挂载目录中的 Go 编译产物
  • -config config.yaml​：指定配置文件路径
    使用相对路径，依赖 -w /app​，实际路径为 /app/config.yaml
  • -port 9000：指定服务监听端口
    与端口映射保持一致（容器内监听 9000）

更新部署#

# 本地构建
make build

# 上传新版本
scp ./bin/oneadmin user@server:/opt/oneadmin/

# 重启服务（systemd）
sudo systemctl restart oneadmin

# 重启服务（Docker）
docker restart oneadmin
bash
评论似乎卡住了，尝试刷新？✨