手动部署

注意

我们推荐你使用 Docker安装 来确保体验的一致性。

准备环境

• Python 3.8 及以上
• MySQL 8.0.11 及以上 / MariaDB 10.4 及以上（Django 4.2 的最低要求，官方 Docker 镜像使用 MariaDB 10.8）
• Redis 5.0 及以上
• Git 2.17.0 及以上（影响新建常规发布申请单）
• rsync、sshfs（文件分发与流水线数据传输需要）、ping（监控 Ping 检测需要）
• 现代浏览器

安装步骤

以下安装步骤假设项目部署在一台 CentOS 7 系统的 /data/spug 目录下，Ubuntu / Debian 仅安装依赖的命令不同。

1. Clone项目代码

git clone https://github.com/openspug/spug /data/spug
cd /data/spug
git checkout v4.0.0

2. 下载已编译打包后的前端项目

将下载好的前端压缩包解压到 spug_web 目录（会生成 build 目录）：

curl -o /tmp/web_v4.0.0.tar.gz https://cdn.spug.cc/spug/web_v4.0.0.tar.gz
tar xf /tmp/web_v4.0.0.tar.gz -C /data/spug/spug_web/

提示

也可以按 二次开发 文档自行执行 npm run build 打包。

3. 创建运行环境

# CentOS 安装依赖
yum install -y mariadb-devel python3-devel gcc pkgconfig openldap-devel cyrus-sasl-devel openssl-devel redis nginx supervisor rsync fuse-sshfs iputils git

# Ubuntu / Debian 安装依赖
# apt install -y libmariadb-dev python3-dev python3-venv gcc pkg-config libldap2-dev libsasl2-dev libssl-dev redis-server nginx supervisor rsync sshfs iputils-ping git

# 创建虚拟环境
cd /data/spug/spug_api
python3 -m venv venv
source venv/bin/activate

# 安装python包
pip install -U pip setuptools -i https://pypi.tuna.tsinghua.edu.cn/simple/
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
pip install mysqlclient -i https://pypi.tuna.tsinghua.edu.cn/simple/   # gunicorn、daphne 已包含在 requirements.txt 中

4. 修改后端配置

后端默认使用的 SQLite 数据库，通过修改配置使用 MySQL 作为后端数据库，如何使用SqlServer数据库？

注意

在 spug_api/spug/ 目录下创建 overrides.py 文件，启动后端服务后会自动覆盖默认的配置，避免直接修改 settings.py 以便于后期获取新版本。

spug_api/spug/overrides.py

DEBUG = False
# 请替换为随机字符串，用于签名会话等安全用途
SECRET_KEY = 'replace-me-with-a-random-string'

DATABASES = {
    'default': {
        'ATOMIC_REQUESTS': True,
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'spug',             # 替换为自己的数据库名，请预先创建好编码为utf8mb4的数据库
        'USER': 'spug_user',        # 数据库用户名
        'PASSWORD': 'spug_passwd',  # 数据库密码
        'HOST': '127.0.0.1',        # 数据库地址
        'OPTIONS': {
            'charset': 'utf8mb4',
            'sql_mode': 'STRICT_TRANS_TABLES',
            #'unix_socket': '/opt/mysql/mysql.sock' # 如果是本机数据库,且不是默认安装的Mysql,需要指定Mysql的socket文件路径
        }
    }
}

5. 初始化数据库

cd /data/spug/spug_api
python manage.py updatedb

6. 创建默认管理员账户

python manage.py user add -u admin -p spug.cc -s -n 管理员

# -u 用户名
# -p 密码
# -s 超级管理员
# -n 用户昵称

7. 创建启动服务脚本

/etc/supervisord.d/spug.ini

[program:spug-api]
command = bash /data/spug/spug_api/tools/start-api.sh
autostart = true
stdout_logfile = /data/spug/spug_api/logs/api.log
redirect_stderr = true

[program:spug-ws]
command = bash /data/spug/spug_api/tools/start-ws.sh
autostart = true
stdout_logfile = /data/spug/spug_api/logs/ws.log
redirect_stderr = true

[program:spug-worker]
command = bash /data/spug/spug_api/tools/start-worker.sh
autostart = true
stdout_logfile = /data/spug/spug_api/logs/worker.log
redirect_stderr = true

[program:spug-monitor]
command = bash /data/spug/spug_api/tools/start-monitor.sh
autostart = true
stdout_logfile = /data/spug/spug_api/logs/monitor.log
redirect_stderr = true

[program:spug-scheduler]
command = bash /data/spug/spug_api/tools/start-scheduler.sh
autostart = true
stdout_logfile = /data/spug/spug_api/logs/scheduler.log
redirect_stderr = true

该配置与仓库中的 spug_api/tools/supervisor-spug.ini 完全相同，也可以直接复制：cp /data/spug/spug_api/tools/supervisor-spug.ini /etc/supervisord.d/spug.ini。各服务说明：spug-api 为 HTTP 接口（gunicorn，127.0.0.1:9001），spug-ws 为 WebSocket 服务（daphne，127.0.0.1:9002），spug-worker 执行批量执行、发布、流水线等任务，spug-monitor 与 spug-scheduler 分别为监控与任务计划的调度进程。Ubuntu / Debian 的 supervisor 配置目录为 /etc/supervisor/conf.d/，文件名后缀为 .conf。

8. 创建前端nginx配置文件

/etc/nginx/conf.d/spug.conf

server {
        listen 80;
        server_name _;     # 修改为自定义的访问域名
        root /data/spug/spug_web/build/;
        client_max_body_size 20m;   # 该值会影响文件管理器可上传文件的大小限制，请合理调整

        gzip  on;
        gzip_min_length  1k;
        gzip_buffers     4 16k;
        gzip_http_version 1.1;
        gzip_comp_level 7;
        gzip_types       text/plain text/css text/javascript application/javascript application/json;
        gzip_vary on;

        location ^~ /api/ {
                rewrite ^/api(.*) $1 break;
                proxy_pass http://127.0.0.1:9001;
                proxy_read_timeout 180s;
                proxy_redirect off;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

        location ^~ /api/ws/ {
                rewrite ^/api(.*) $1 break;
                proxy_pass http://127.0.0.1:9002;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }

        location / {
                try_files $uri /index.html;
        }
}

注意

注意：如果你没有在 spug.conf 中指定 server_name 则需要把 /etc/nginx/nginx.conf 中默认的 server 块注释或删除后才能正常访问， 否则会打开 Nginx 默认页面。

9. 启动服务

# 设置开机启动
systemctl enable nginx
systemctl enable redis
systemctl enable supervisord

# 启动服务
systemctl restart nginx
systemctl restart redis
systemctl restart supervisord

10. 访问测试

通过浏览器访问测试（默认账户密码在第 6 步设置）。

11. 安全建议

• 请确保安装的 Redis 仅监听在 127.0.0.1。如果需要使用密码认证的 Redis 请参考 如何配置使用带密码的 Redis 服务？
• 如添加外层代理服务，请正确配置 HTTP Header 的 X-Forwarded-For，Spug 会使用该请求头提高安全性（当登录用户的 IP 发生变化时 Token 自动失效），参考文档。
• 建议在 系统设置 / 安全设置 中开启登录 MFA，并通过防火墙限制访问来源。