单机部署

本文说明 ovra-zero 在单台服务器上的部署流程，适合开发测试、小型内网环境和正式上线前验证。整体步骤参考“准备工作、运行系统、必要配置、部署系统、常见问题”的手册结构，尽量保证可以照着执行。

准备工作

环境要求

环境	版本建议	说明
Go	`1.24+`	构建后端服务
MySQL	`8.0+`	业务数据库
Redis	`7+`	缓存、验证码、幂等控制
etcd	`3.5+`	go-zero RPC 服务发现
Traefik	可选	本地或单机统一网关

服务端口

服务	REST 端口	RPC 端口	Prometheus
auth	`8091`	-	`4001`
system	`8092`	`9092`	`4002`
demo	`8099`	`9099`	`4009`
Traefik	`28080`	-	-

代码目录

git clone https://github.com/cls-cloud/ovra-zero.git
cd ovra-zero

初始化工具和依赖：

make init

初始化数据库

创建数据库：

CREATE DATABASE ovra_zero DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入初始化脚本：

mysql -uroot -p ovra_zero < bin/sql/ovra_zero.sql

默认账号密码：

admin/admin123

tip

如果 Linux 上提示表不存在，但数据库中可以看到表，检查 MySQL 是否开启了大小写敏感。建议在部署前统一数据库大小写规则，避免不同系统之间迁移后出现表名不匹配。

必要配置

单机部署默认使用 dev 环境配置：

etc/dev/common.yaml
etc/dev/auth.yaml
etc/dev/system.yaml
etc/dev/demo.yaml

服务启动时会先读取同目录下的 common.yaml，再读取具体服务配置，并用服务配置覆盖公共配置。

数据库配置

编辑 etc/dev/common.yaml：

Data:
  Database:
    Username: root
    Password: Pl@1221view
    Host: 127.0.0.1
    Port: 3306
    Database: ovra_zero

生产环境请替换默认密码，并确认数据库用户只授予必要权限。

Redis 配置

Data:
  Redis:
    Pass: Pl@1221view
    Host: 127.0.0.1:6379
    Type: node
    Tls: false

单机 Redis 使用 Type: node。如果改成 Redis Cluster，需要同步调整 Redis 地址和类型。

etcd 配置

RpcConf:
  Etcd:
    Hosts:
      - 127.0.0.1:2379

SystemRpc:
  Etcd:
    Hosts:
      - 127.0.0.1:2379

system 和 demo 会把 RPC 服务注册到 etcd；auth 会通过 SystemRpc 调用 system。

安全配置

上线前建议检查：

JwtAuth.AccessSecret：替换为自有密钥。
Data.Redis.Pass：替换默认 Redis 密码。
ApiDecrypt、Rsa：如果前端启用接口加密，前后端密钥必须一致。
Tenant.Enabled：按业务需要决定是否开启租户隔离。

运行系统

开发联调可以直接运行源码：

ENV=dev go run app/system/system.go
ENV=dev go run app/auth/auth.go
ENV=dev go run app/demo/demo.go

也可以显式指定配置文件：

go run app/system/system.go -f etc/dev/system.yaml
go run app/auth/auth.go -f etc/dev/auth.yaml
go run app/demo/demo.go -f etc/dev/demo.yaml

推荐启动顺序：

启动 MySQL、Redis、etcd。
启动 system，注册 system.rpc。
启动 auth。
启动 demo。
启动 Traefik 或前端网关。

启动成功后可验证：

curl -sS http://127.0.0.1:8091/auth/code

如果使用 Traefik：

make traefik-run
curl -sS http://127.0.0.1:28080/auth/code

部署系统

构建服务

make build-all

生成的二进制位于项目根目录：

auth
system
demo

单独构建：

make build-auth
make build-system
make build-demo

后台启动

ENV=dev ./system > system.log 2>&1 &
ENV=dev ./auth > auth.log 2>&1 &
ENV=dev ./demo > demo.log 2>&1 &

查看日志：

tail -f system.log
tail -f auth.log
tail -f demo.log

systemd 托管

正式服务器建议使用 systemd 管理进程。示例 ovra-system.service：

[Unit]
Description=Ovra Zero System
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/ovra-zero
Environment=ENV=dev
ExecStart=/opt/ovra-zero/system
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

auth、demo 只需要替换 Description 和 ExecStart。

启用服务：

systemctl daemon-reload
systemctl enable --now ovra-system
systemctl status ovra-system

上线检查

部署完成后建议逐项检查：

检查项	命令
服务端口	`ss -lntp \| grep -E '8091
etcd 健康	`etcdctl endpoint health --endpoints=http://127.0.0.1:2379`
Redis 连通	`redis-cli -a 'Pl@1221view' ping`
登录验证码	`curl -sS http://127.0.0.1:8091/auth/code`
网关转发	`curl -sS http://127.0.0.1:28080/auth/code`

常见问题

提示配置文件不存在

确认当前工作目录是项目根目录，并且 ENV 对应目录存在：

pwd
ls etc/dev

未设置 ENV 时默认读取：

etc/dev/<service>.yaml

auth 启动后调用 system 失败

先确认 system 已启动，并且已注册 RPC：

etcdctl --endpoints=http://127.0.0.1:2379 get system.rpc --prefix

如果没有注册信息，检查 system 日志和 RpcConf.Etcd.Hosts。

MySQL 连接失败

检查 etc/dev/common.yaml 中的数据库地址、账号、密码和库名。确认初始化 SQL 已导入：

mysql -uroot -p -e "USE ovra_zero; SHOW TABLES;"

Redis 认证失败

确认 Redis 实际密码与 Data.Redis.Pass 一致。如果 Redis 没有密码，可以清空该字段。

文件或日志无权限

systemd 部署时确认运行用户对项目目录、日志目录和上传目录有读写权限。

准备工作​

环境要求​

服务端口​

代码目录​

初始化数据库​

必要配置​

数据库配置​

Redis 配置​

etcd 配置​

安全配置​

运行系统​

部署系统​

构建服务​

后台启动​

systemd 托管​

上线检查​

常见问题​

提示配置文件不存在​

auth 启动后调用 system 失败​

MySQL 连接失败​

Redis 认证失败​

文件或日志无权限​