Spug軟件使用說明書

關於Spug

介紹

Spug 面向中小型企業設計的輕量級無 Agent 的自動化運維平台，整合了主機管理、主機批量執行、主機在線終端、文件在線上傳下載、應用發布部署、在線任務計划、配置中心、監控、報警等一系列功能。

特性

• 批量執行: 主機命令在線批量執行
• 在線終端: 主機支持瀏覽器在線終端登錄
• 文件管理: 主機文件在線上傳下載
• 任務計划: 靈活的在線任務計划
• 發布部署: 支持自定義發布部署流程
• 配置中心: 支持 KV、文本、json 等格式的配置
• 監控中心: 支持站點、端口、進程、自定義等監控
• 報警中心: 支持短信、郵件、釘釘、微信等報警方式
• 優雅美觀: 基於 Ant Design 的 UI 界面

預覽

快速開始

Docker安裝

依賴環境

• Docker
• 現代瀏覽器

安裝步驟

以下安裝步驟使用CentOS7.x操作系統

1. 安裝docker

注意
如已安裝 docker 則忽略。
以下安裝 docker 步驟適用於 Centos，其他系統安裝請參考 Docker官方文檔。

yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
yum install docker-ce docker-ce-cli containerd.io
systemctl start docker

2. 拉取鏡像

docker pull registry.aliyuncs.com/openspug/spug

3. 啟動容器

如果需要持久化存儲代碼和數據，可以添加：-v 映射容器內/data路徑。

鏡像內置了 Mysql 數據庫。
根據需要，以下兩種啟動方式任選其一即可。

# 持久化存儲啟動命令：
# /spug 指的是映射本地的磁盤路徑，也可以是其他目錄，/data是容器內代碼和數據初始化存儲的路徑
docker run -d --restart=always --name=spug -p 80:80 -v /spug:/data registry.aliyuncs.com/openspug/spug

# 如果你需要在spug內使用docker命令則需要添加額外的參數
docker run -d --restart=always --name=spug -p 80:80 -v /spug/:/data -v /var/run/docker.sock:/var/run/docker.sock -v /usr/bin/docker:/usr/bin/docker registry.aliyuncs.com/openspug/spug

4. 初始化
   以下操作會創建一個用戶名為 admin 密碼為 spug.dev 的管理員賬戶，可自行替換管理員賬戶。

如果提示連接數據失敗，再次執行嘗試就可以了。

docker exec spug init_spug admin spug.dev

5. 訪問測試
   在瀏覽器中輸入 http://localhost:80 訪問。

用戶名： admin  
密碼： spug.dev

安裝相關問題

執行數據初始化命令 python manage.py updatedb 報錯

一般有以下兩種情況

• Django 版本使用了 3.x 的版本，我們僅支持 2.2.x 版本，安裝依賴推薦使用文檔中的 pip install -r requirements.txt 來安裝。
• 系統的 Sqlite 版本太低，Django 2.2 Sqlite 的版本最低要求為 3.8.3。

Nginx 訪問前端文件提示無權限問題

確認系統是否開啟了 selinux。如果開啟可通過執行 setenforce 0 來臨時關閉后重試。

登錄報錯 請求失敗: 504 Gateway Timeout

請確保 api 服務是否啟動，如果已啟動則可以通過控制台查看是否監聽在 8000 端口，如果不是 8000 端口可以改為 8000 端口或者修改前端項目的 spug/spug_web/src/setupProxy.js 文件中的 target 值為你的 api 服務的監聽地址和端口。

登錄報錯 請求失敗: 502 Bad Gateway

請確保 api 服務已正常啟動且 nginx 配置正確。另可查看 nginx 日志如有發現 13: Permission denied 字樣的報錯則可嘗試關閉 selinux 后再測試。

登錄報錯 Exception: Error 61 connecting to 127.0.0.1:6379. Connection refused.

需要安裝 Redis，如果安裝的 Redis 不是監聽在 127.0.0.1 需要修改配置文件 spug_api/spug/settings.py 指定 Redis 的 Host，配置中的 CACHES 和 CHANNEL_LAYERS 均使用了 Redis。

添加主機報錯 Exception: not a vaild RSA private key file

當 Spug 生成的密鑰對無法通過驗證時，會嘗試讀取系統的 ~/.ssh/ 目錄下的密鑰進行驗證，這個報錯一般是在讀取系統密鑰時出錯。 可以嘗試先移除系統 的密鑰，然后再操作添加主機，等添加完成后再恢復原有的密鑰。

如何配置使用帶密碼的 Redis 服務？

假設 Redis 密碼為 foo123，則需要更改以配置文件 spug_api/spug/overrides.py（推薦） 或者 settings.py（影響后續版本升級） 如下內容，修改完成后記得重啟服務。

提示
自定義的配置可以在 spug_api/spug/ 目錄下創建 overrides.py 文件來覆蓋默認的配置。

vi spug_api/spug/overrides.py
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://:foo123@127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        }
    }
}

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": ["redis://:foo123@127.0.0.1:6379/0"],
        },
    },
}

Docker 部署使用外部 Mysql

官方 Docker 鏡像內置了數據庫服務，如果你想使用自己的外部數據庫，可以通過如下方法：

注意
如果需要遷移數據，請查看 版本升級注意事項，以免造成后期無法升級新版本。

# 1. 進入容器
docker exec -it spug bash

# 2. 修改配置文件使訪問外部數據庫
vi /data/spug/spug_api/spug/overrides.py

DATABASES = {
    'default': {
        'ATOMIC_REQUESTS': True,
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'spug',
        'USER': 'spug',  # 修改為外部數據庫的用戶
        'PASSWORD': 'spug.dev',  # 修改為外部數據的用戶密碼
        'HOST': 'localhost',    # 修改為外部數據的ip
        'OPTIONS': {
            'unix_socket': '/var/lib/mysql/mysql.sock',   # ！！！刪除該行
            'charset': 'utf8mb4',
            'sql_mode': 'STRICT_TRANS_TABLES',
        }
    }
}

# 3. 停止容器內的數據庫服務
vi /etc/supervisord.d/spug.ini

# 找到如下行並刪除
[program:mariadb]
command = /usr/libexec/mysqld --user=mysql
autostart = true

# 4. 退出並重啟容器
exit
docker restart spug

使用常見問題

使用 nohup 啟動后台進程頁面一直在轉圈不會結束？

在 批量執行 或 發布配置 等的執行腳本中以 nohup 或 & 的方式啟動后台子進程時需要 把命令的標准輸出重定向至 /dev/null，例如以下啟動 Tomcat 的命令：

cd web/WEB-INF/
nohup ./startup.sh &

把上述命令改為：

cd web/WEB-INF/
nohup ./startup.sh > /dev/null &

能否使用自己的密鑰對？

可以，v2.3.0 版本開始已支持上傳自定義密鑰對，可以在 系統管理 \ 系統設置 \ 密鑰設置 中，自行上傳密鑰。

新建常規發布申請 git clone 錯誤

Spug 無法提供交互式的輸入賬戶密碼登錄git倉庫的能力，如果是公開的倉庫 http/https/ssh 任何一種協議都可以，但如果是私有倉庫推薦使用 ssh 協議配置密鑰來訪問。http/https 協議則需要在帶上用戶名和密碼，例如 https://yourname:[e-mail]/openspug/spug.git 如果賬戶名中包含了 @ 符號，則需要替換成 %40。特別要注意的是，如果你是通過docker方式部署的則需要確保在容器內可以訪問倉庫，而不是在宿主機上。

主機 Console 或執行發布頁面無內容

這種情況大部分都是 Websocket 連接建立失敗了，一般出現在部署時自己加了一層 nginx 之類的代理工具，這些代理工具默認無法處理 Weboscket 請求， 這就需要你配置其支持轉發 Websocket 請求，下邊給個 Nginx 的例子，這里假設你用 docker 部署的 Spug, 映射了宿主機的 8000 端口：

server {
  listen 80;
  server_name xxx.xxx.xxx;
  
  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
 
  location ^~ /api/ws/ {
    proxy_pass http://127.0.0.1:8000;
    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;
  }

  error_page 404 /index.html;
}

文件管理器上傳文件報錯 413 Request Entity Too Large

文件上傳大小受 Nginx 的 client_max_body_size 影響，請修該值至合適的大小，參考以下配置：

注意
docker 方式部署配置文件位於容器內的 /etc/nginx/nginx.conf, 可以在容器外部編輯后通過 docker cp 至容器內，也可以在容器內執行 vi 在容器內直接修改，最后別忘了重啟容器。

server {
  listen 80;
  server_name xxx.xxx.xxx;
  client_max_body_size 100m;

  ...
}

釘釘收不到通知？

釘釘機器人安全設置中 IP地址 添加部署 Spug 的服務器的公網地址，或者使用 自定義關鍵詞 填寫 通知，如下圖

二開相關問題

標准安裝批量執行的任務卡住無法看到執行輸出

批量執行功能需要啟動額外服務，通過以下命令啟動，以下操作命令基於 標准安裝 文檔的環境

cd /data/spug/spug_api
source venv/bin/activate
python manage.py runworker

標准安裝任務計划模塊添加的任務不會執行

任務計划功能需要啟動額外的服務，通過以下命令啟動，以下操作命令基於 標准安裝 文檔的環境

cd /data/spug/spug_api
source venv/bin/activate
python manage.py runscheduler
python manage.py runworker

標准安裝監控中心模塊添加的監控任務不會執行

監控中心功能需要啟動額外的服務，通過以下命令啟動，以下操作命令基於 標准安裝 文檔的環境

cd /data/spug/spug_api
source venv/bin/activate
python manage.py runmonitor
python manage.py runworker

macOS 如何使用 Mysql 替代默認的 Sqlite 數據庫？

需要安裝 mysqlclient 數據庫驅動庫，可通過以下步驟安裝

brew install mysql-client
export PATH="/usr/local/opt/mysql-client/bin:$PATH"
export LDFLAGS="-I/usr/local/opt/openssl/include -L/usr/local/opt/openssl/lib"
pip install mysqlclient

FAQ

驗證主機時我輸入的密碼安全嗎？

安全，你輸入的密碼僅用於當次建立密鑰登錄使用，並不會存儲在任何地方或用於他處。

我不需要監控中心的功能，可以不啟動 runmonitor 服務嗎？

可以，包括任務計划模塊，如果你不需要這個功能，也不必啟動 runscheduler 服務。

內置的報警服務為什么不開源直接放在項目內呢？

因為不管是微信/郵件/短信都需要配置一些敏感信息才可以使用，例如微信的 APP_ID 郵件服務的賬戶密碼等，所以暫無法開源。 另外我們也在系統設置的報警服務設置中提供了自定義郵件服務的相關配置，以便你使用自己的郵件服務。

使用手冊

主機管理

介紹

管理維護平台可操作的主機，首次添加主機時需要輸入 ssh 指定用戶的密碼。

原理說明

Spug 會在首次添加主機時嘗試直接通過密鑰連接目標主機，會出現以下3種可能：

1. 如果目標主機不支持密鑰認證，則直接拋出異常（錯誤代碼 E01）並終止請求。
2. 如果認證通過則直接完成主機添加。
3. 如果認證失敗，則彈出密碼輸入框，讓用戶輸入密碼然后設置密鑰認證。
   當第 3 種情況時用戶輸入密碼，Spug 在接收到輸入的密碼后，會嘗試通過密碼連接目標主機並執行以下命令設置密鑰認證

mkdir -p -m 700 ~/.ssh
echo 'public key content ....' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

完成以上操作后，會再次嘗試使用密鑰連接目標主機，會出現以下2中可能：

1. 認證失敗，則直接拋出異常（錯誤代碼 E02）並終止請求。
2. 認證通過，完整主機添加。

錯誤說明

• E01 表示目標主機不支持密鑰認證，通常可以嘗試查看目標主機的 sshd 配置文件 /etc/ssh/sshd_config 確保 PubkeyAuthentication yes。
• E02 在 Spug 嘗試設置密鑰認證后依然無法正常通過密鑰連接主機，如果你的目標主機 OpenSSH 版本 8.8 以上版本，則需要在 /etc/ssh/sshd_config 末尾添加一行配置 PubkeyAcceptedKeyTypes +ssh-rsa，然后重啟 sshd 服務后再嘗試。其他情況需要你自行查看具體原因（確保~/.ssh目錄的權限 700 ， ~/.ssh/ 目錄下所有文件權限600），如果你可以手動操作實現密鑰認證可自己嘗試實現密鑰認證，測試通過后再次添加主機即可。

批量執行

介紹

包含維護命令模版和批量遠程執行命令兩部分功能，常用來執行一些臨時的任務例如，批量安裝/卸載某個依賴包等。

執行任務

可以選擇一到多個在主機管理中添加的主機作為執行的目標主機，命令內容可以直接寫也支持從模板中讀取已保存的命令。

提示
使用 nohup 或 & 啟動后台進程頁面一直在轉圈不會結束？

全局變量

在 Shell 腳本中通過 $SPUG_HOST_HOSTNAME 來引用，在 Python 腳本中可以通過 os.getenv('SPUG_HOST_HOSTNAME') 來引用。

變量名	示例	說明
SPUG_HOST_ID	1	主機ID
SPUG_HOST_HOSTNAME	172.10.26.5	主機IP/域名
SPUG_SSH_PORT	22	SSH連接端口
SPUG_SSH_USERNAME	root	SSH連接用戶名
SPUG_INTERPRETER	python	命令解釋器

模板管理

用於存儲復雜、常用的命令集合，以便后期可隨時使用。

應用發布

應用管理

介紹

管理和維護可發布的應用。 每個應用又可以創建對應環境的發布配置，發布配置請查看發布配置文檔。

配置項

• 應用名稱 自定義的應用名稱
• 唯一標識符 會作為配置中心生成配置 Key 的前綴，具體請參考配置中心相關文檔。
  小提示
• 配置中心和應用發布模塊都可以創建應用，它們的數據是互通的。
• 環境的創建功能，在配置中心模塊的環境管理頁面。

發布配置

介紹

配置指定應用在某環境下如何執行發布，發布支持兩種方式 常規發布 和 自定義發布。

常規發布

由 Spug 負責應用代碼的打包、傳輸和更新，但提供了各個階段可自定義的鈎子。

說明
常規發布參考了開源項目 瓦力 的一些設計思路。

配置項

• 發布環境 為哪個環境創建的發布配置，例如：測試環境 / 生產環境等。
• Git倉庫地址 該應用的 Git 倉庫地址（請確保部署運維平台的服務器有權限通過給定的地址克隆倉庫）。
• 發布審核 開啟后創建的發布申請單需要審核后才可以進行發布。
• 目標主機部署路徑 應用部署的路徑，例如：靜態網站部署在目標服務器的 /var/www/html。
• 目標主機倉庫路徑 用於存儲應用的歷史版本，可自定義任意目錄，例如：/data/spug/repos。
• 保留歷史版本數量 即如上邊的例子中 /data/spug/repos 保留的歷史版本數量，超過后早起的版本會自動刪除，以節約存儲空間。
• 發布目標主機 可以選擇一個或多個主機進行發布。
• 文件過濾 可選 僅包含 或 排除 指定的文件，會從克隆的 Git 倉庫的源代碼中根據指定的規則過濾出符合條件的文件進行發布。
• 自定義全局變量 可在后邊的鈎子命令內使用，Spug 本身也包含一些內置全局變量，請參考下文。
• 代碼遷出前執行 在部署 Spug 的服務器上運行，可以執行任意自定義命令。
• 代碼遷出后執行 在部署 Spug 的服務器上運行，當前目錄為檢出后待發布的源代碼目錄，可執行任意自定義命令。
• 應用發布前執行 在發布的目標主機上運行，當前目錄為目標主機上待發布的源代碼目錄，可執行任意自定義命令。
• 應用發布后執行 在發布的目標主機上運行，當前目錄為已發布的應用目錄，可執行任意自定義命令。

提示
使用 nohup 或 & 啟動后台進程頁面一直在轉圈不會結束？

自定義發布

該發布模式下 Spug 僅負責按順序依次執行記錄的動作。

配置項

• 發布環境 為哪個環境創建的發布配置，例如：測試環境 / 生產環境等。
• 發布審核 開啟后創建的發布申請單需要審核后才可以進行發布。
• 發布目標主機 可以選擇一個或多個主機進行發布。
• 本地執行動作 可以添加多個執行動作，執行對象為部署運維平台的服務器，會優先按順序執行本地動作。
• 目標主機執行動作 可以添加多個執行動作，執行對象為發布的目標主機，按順序依次執行。
• 數據傳輸動作 用於文件分發傳輸，

提示
使用 nohup 或 & 啟動后台進程頁面一直在轉圈不會結束？

數據傳輸

從 v2.3.7 版本開始已支持添加數據傳輸動作，用於把文件從部署 Spug 的容器或主機傳輸至目標主機，其頁面展示效果如下：

• 數據來源 數據來源可以選擇以下兩種
  • 本地路徑：位於部署 spug 的容器或主機上，路徑可以是文件或目錄，請輸入絕對路徑。
  • 發布時上傳：在創建發布申請時上傳數據。
• 過濾規則 僅在數據來源選擇本地路徑時有效，可以設置包含 和 排除兩種規則，內容為基於本地路徑的相對路徑，多個路徑使用英文逗號分割，當傳輸對象為文件時過濾規則將會被忽略。
• 目標路徑 如果數據來源為發布時上傳，則目標路徑必須為一個文件路徑（例如：/tmp/upload.tar.gz）, 如果數據來源為本地路徑則請保持目標路徑與本地路徑的類型一致，如本地路徑為文件則目標路徑也必須為文件，可參考以下例子
  當數據來源為發布時上傳，需要注意以下事項：

注意
目標路徑必須為文件路徑，例如：/data/upload.jar，大部分情況下還需要其他后續動作去處理上傳的文件。
上級目錄必須已存在，如上例子則 /data 必須為目標主機上已存在的目錄。
每次執行該數據傳輸動作時將會覆蓋已存在的文件。

下面以 Spug 開源項目的源代碼作為例子來說明當數據來源為本地路徑時幾種典型情況，假設源代碼位於 /data/spug 目錄下。

• 本地路徑：/data/spug，目標路徑：/www/spug，文件過濾：關閉

說明
將會把部署 Spug 的容器或主機上的 /data/spug 目錄完整傳輸至目標主機的 /www/spug 目錄，特別注意，如果目標主機的 /www/spug 已存在，將會先執行刪除操作。

• 本地路徑：/data/spug，目標路徑：/www/spug，文件過濾：包含 spug_api,spug_web/dist

說明
僅把 /data/spug 目錄下的 spug_api 和 spug_web/dist 傳輸至目標主機，傳輸完成后目錄主機的 /www/spug 中僅包含上述兩個目錄，文件 過濾中的 排除 用法與 包含 類似，但只傳輸除了指定路徑以外的其他文件。

• 本地路徑：/data/spug/README.md，目標路徑：/www/spug/README.md, 文件過濾：包含 spug_api

說明
僅把 README.md 傳輸至目標主機，因為傳輸對象為文件，所以文件過濾規則將會被忽略。

• 本地路徑：/data/spug/README.md, 目標路徑：/www/spug，文件過濾：關閉

說明
傳輸 README.md 至目標主機，刪除並替換 /www/spug，特別注意，傳輸完成后目標主機的 /www/spug 將變更為一個文件，內容為 README.md 文件的內容。這個是一個反例，如果你要傳輸的是文件，請保持目標路徑也是一個完整的文件路徑。

• 本地路徑：/data/spug, 目標路徑：/www/spug/README.md，文件過濾：關閉

說明
將傳輸整個 /data/spug 目錄至目標主機並將其命名為 README.md，特別注意，傳輸完成后目標主機的 /www/spug/README.md 將變更為一個目錄。 這個是一個反面例子，如果你要傳輸的是目錄，請保持目標路徑也是一個完整的目錄路徑。

全局變量

• SPUG_APP_NAME 發布應用的名稱
• SPUG_APP_KEY 發布應用的標識符
• SPUG_APP_ID 發布應用的 ID
• SPUG_REQUEST_ID 發布申請單 ID
• SPUG_REQUEST_NAME 發布申請單的名稱
• SPUG_VERSION 發布申請版本
• SPUG_BUILD_VERSION 發布申請內部版本號（v3.0.5新增）
• SPUG_ENV_ID 發布環境 ID
• SPUG_ENV_KEY 發布環境的標識符
• SPUG_DEPLOY_ID 發布配置 ID（v2.2.3新增）
• SPUG_DEPLOY_TYPE 發布類型（"1" 為正常發布，"2" 為回滾）
• SPUG_API_TOKEN 訪問配置中心獲取配置的 API_TOKEN
• SPUG_HOST_ID 當前執行主機的 ID（v2.2.3新增，僅在主機執行階段有效）
• SPUG_HOST_NAME 當前執行主機的 IP /域名（v2.2.3新增，僅在主機執行階段有效）

常規發布有效

• SPUG_REPOS_DIR 常規發布源碼存儲目錄（v2.3.4新增，\(SPUG_REPOS_DIR/\)SPUG_DEPLOY_ID 即為本次發布應用的源碼目錄）
• SPUG_DST_DIR 常規發布目標主機部署路徑（v2.3.8新增）
• SPUG_GIT_BRANCH 本次發布選擇的 Git 分支（v2.3.2新增，常規發布基於分支時有效）
• SPUG_GIT_COMMIT_ID 本次發布選擇的Git Commit ID（v2.3.2新增，常規發布基於分支時有效）
• SPUG_GIT_TAG 本次發布的Git Tag（v2.3.2新增，常規發布基於 Tag 時有效）

自定義發布有效

• SPUG_RELEASE 新建自定義發布申請填寫的 SPUG_RELEASE 值（自定義發布有效）

提示
SPUG_RELEASE 會自動按空格分隔解析為多個環境變量，例如 abc 123 def，會對應有4個變量：

SPUG_RELEASE = abc 123 def
SPUG_RELEASE_1 = abc
SPUG_RELEASE_2 = 123
SPUG_RELEASE_3 = def

發布申請

介紹

創建和執行發布。

配置項

根據發布方式的不同，對應創建發布申請的配置項也不同。

常規發布

• 申請標題 申請單的名稱。
• 選擇分支/標簽/版本 支持選擇分支和 CommitID 或 Tag 來確定發布的代碼。
• 發布目標主機 可選擇本次申請單要發布的主機（從發布配置添加的目標主機中選擇）。

自定義發布

• 申請標題 申請單的名稱。
• 環境變量（SPUG_RELEASE） 可以在自定義腳本中引用該變量，用於設置本次發布相關的動態變量，可在發布配置添加的動作腳本中通過 $SPUG_RELEASE 來使用該值。
• 發布目標主機 可選擇本次申請單要發布的主機（從發布配置添加的目標主機中選擇）。

發布記錄的刪除

可以發現發布申請在發布后無法被單個直接刪除，這並不是我們偷懶，而是故意設計成這樣的。以我們以往的經驗來看發布記錄在某些情況下是重要的排查問題的線索， 例如，某用戶在未充分測試的情況下通過 Spug 發布一個應用的新版本，很不巧這個新版本上線后發現了問題造成了服務不可用的情況，出於一些原因該用戶把這個發布記錄悄悄的刪除了， 那么這個行為可能就會在排查問題的時候造成一定的困擾。所以我們只設計了根據時間和保留個數兩個維度來批量刪除，避免可能遇到的上述問題。

小提示

• 如果發布配置中啟用了審核功能，則創建的申請單需要通過審核后才可以執行發布操作。

回滾機制

介紹

發布目前支持兩種方式 常規發布 和 自定義發布，這里來分別講解下這兩種發布方式的回滾機制。

常規發布

常規發布由發布配置中的 保留歷史版本數量 來決定是否可以回滾，超過保留上限的版本將無法執行回滾操作。回滾將經歷以下幾個步驟：

1. 當用戶在發布申請中點擊 回滾 按鈕時，將會自動基於本次發布的上個版本（例如：有 v1.1.3 v1.1.2 v1.1.1 三個發布記錄，當點擊 v1.1.3 的回滾按鈕時將基於 v1.1.2，同理點擊v1.1.2 時將基於 v1.1.1）創建新的發布申請。
2. 找到第一步所創建的帶有 回滾 字樣標題的發布申請，如果開啟了審核則需要先通過審核，否則可直接點擊發布按鈕。
3. 執行回滾發布，回滾發布將跳過檢出前后動作，直接執行發布前和發布后任務並使用存儲的歷史版本發布。
   如果你想控制回滾時行為執行不同的操作，可以在 發布前任務 和 發布后任務 中使用內置的全局變量 SPUG_DEPLOY_TYPE， 通過判斷其值來做不同的操作。

自定義發布

因為自定義發布更加的靈活自由，Spug 也無法對回滾進行任何限制或干涉，完全依靠用戶來控制。回滾將經歷以下幾個步驟：

1. 與常規發布相同，當用戶在發布申請中點擊 回滾 按鈕時，將會自動基於本次發布的上個版本（例如：有 v1.1.3 v1.1.2 v1.1.1 三個發布記錄，當點擊 v1.1.3 的回滾按鈕時將基於 v1.1.2，同理點擊v1.1.2 時將基於 v1.1.1）創建新的發布申請。
2. 找到第一步所創建的帶有 回滾 字樣標題的發布申請，如果開啟了審核則需要先通過審核，否則可直接點擊發布按鈕。
3. 執行回滾發布，默認行為與發布一致，會根據定義的順序完整執行所有動作。
   如果你想控制回滾時行為執行不同的操作，在自定義的動作中使用內置的全局變量 SPUG_DEPLOY_TYPE， 通過判斷其值來做不同的操作。

控制行為

內置的全局變量 SPUG_DEPLOY_TYPE 可用於區分回滾和正常發布，1 為正常發布， 2 為回滾發布。 用戶可通過判斷其值來實現不同情況下的不同操作， 例如：

if [ "$SPUG_DEPLOY_TYPE" = "1" ]; then
    echo "執行正常發布的操作，巴啦啦..."
else
    echo "這里只有回滾時才會執行"
fi

配置中心

環境管理

介紹

管理應用的運行環境，一般包含開發環境、測試環境和生產環境，應用發布和配置管理需要用它來區分不同的環境。
創建環境時設置的 唯一標識符 用於配置中心提供的開放 API 調用。

服務管理

介紹

管理和維護應用依賴的服務配置。例如有兩個應用 A 和應用 B，它們共同使用一個數據庫，那么就可以把這個數據庫提取出來作為單獨的服務來管理。 這樣帶來的好處是如果這個數據庫配置變更了，那么只需要在服務管理里把這個數據庫的配置更新即可，不必在多個應用之間切換查找更新。

小提示

• 如果某些配置是多個應用共用配置，請考慮把這些配置提取出來作為單獨的服務。
• 服務配置沒有 私有 和 公共 的區分，也可以說所有的服務配置都是 公共 配置。
• 服務配置並不能直接被獲取到，只能通過被依賴的應用獲取到。

應用管理

介紹

用於維護應用的配置，應用配置包含 公共 和 私有 兩種類型的配置。

• 公共 配置

該類型的配置可以被其他應用所使用。比較典型的例子：應用 B 需要調用應用 A 的某接口，那么應用 B 必然需要知道應用 A 的 IP 或域名，這時就可以在應用 A 上添加個 公共 類型的配置以供應用B來使用。為什么不把這個配置放在應用 B 里呢？因為如果還有應用 C / D / E / F 也要調用A呢？在 C / D / E / F 中都配 置一遍即麻煩又難以維護。

• 私有 配置

僅用於此應用的配置，並不會被其他應用所獲取到。

小提示

• 公共 和 私有 類型的配置都會應用自身獲取到，它們區別僅僅是當其他應用依賴該應用時，公共 配置會提供給依賴應用而 私有 配置不會。
• 配置中心用於解決不同環境間配置的差異，如果各個環境下某配置的值都是相同的，就可以直接在代碼中硬編碼而不需要把這些配置放到配置中心維護。

配置管理

介紹

用戶維護服務和應用在不同環境下的具體配置。

小提示

• 當需要一次性錄入大量配置時可以使用 文本模式 或 JSON模式。
• 當使用 文本模式 或 JSON模式 創建應用的配置時默認會創建為 私有 配置。

API

介紹

配置中心提供了開放的接口用於獲取應用在某環境下的配置。

規則

應用的配置將從以下途徑獲取並進行組合：

• 該應用在指定環境下的 公共 和 私有 配置
• 所依賴的應用的 公共 配置
• 所依賴的服務的配置
• 根據指定的環境，僅讀取指定環境的以上配置

獲取方式

配置的獲取需要通過調接口的形式來獲取，根據需要傳的參數又分以下兩種途徑

在發布配置的鈎子內獲取

• 請求地址：/api/apis/config/

• 請求方法： GET

• 請求參數：

參數名	類型	必填	默認值	示例	說明
apiToken	string	是		$SPUG_API_TOKEN	固定值，Spug 內置的全局變量，僅可在發布配置的鈎子中引用
format	string	否	kv	json	返回的格式，目前支持 kv 、env 和 json 三種格式，分別對應 key = value 、 key=value 和 {"key": "value"}，其中 env 為 v2.3.8 新增
noPrefix	string	否		1	v2.3.8 新增，默認返回的 key 會增加應用或服務的標示作為前綴來確保不會出現同名的 key 造成配置的意外覆蓋問題，如果不需要這一特性可以傳該參數來禁用這一默認行為

• 使用示例

以下截圖即在 應用發布前 中調用了獲取配置的接口，將會把該應用該環境下的配置保存在 .env 文件中。

獨立使用

• 請求地址：/api/apis/config/

• 請求方法： GET

• 請求參數：

參數名	類型	必填	默認值	示例	說明
apiKey	string	是		JLV8IGO0DhoxcM7I	調用接口的訪問憑據，在 Spug 系統管理/系統設置/開放服務設置 中配置，請勿泄露給他人
app	string	是		order	指定要獲取其配置的應用的標識符（創建應用時設置的該標識符，請在應用管理或應用配置頁面查看應用的標識符）
env	string	是		dev	指定獲取應用所在環境的標識符（創建環境時設置的該標識符，請在 配置中心/環境管理頁面查看環境標識符）
format	string	否	kv	json	返回的格式，目前支持 kv 、env 和 json 三種格式，分別對應 key = value 、 key=value 和 {"key": "value"}，其中 env 為 v2.3.8 新增
noPrefix	string	否		1	v2.3.8 新增，默認返回的 key 會增加應用或服務的標示作為前綴來確保不會出現同名的 key 造成配置的意外覆蓋問題，如果不需要這一特性可以傳該參數來禁用這一默認行為

• 使用示例1

curl "https://demo.spug.dev/api/apis/config/?apiKey=JLV8IGO0DhoxcM7I&app=order&env=test"

輸出如下

db_order_database = order
db_order_host = 172.26.89.90
db_order_password = 123456
db_order_port = 3306
db_order_username = root
order_app_debug = true
order_cache_driver = file
order_url = http://test-order.internal.com
redis_host = 127.0.0.1
redis_password = 123456

• 使用示例2

curl "https://demo.spug.dev/api/apis/config/?apiKey=JLV8IGO0DhoxcM7I&app=order&env=test&noPrefix=1"

輸出如下

app_debug = true
cache_driver = file
database = order
host = 127.0.0.1
password = 123456
port = 3306
url = http://test-order.internal.com
username = root

說明
可以通過對比發現，在 noPrefix 模式下，服務 訂單主庫（標識符 db_order）的配置 host 和 password 被服務 Redis服務（標識符 redis）覆蓋了，所以最終的配置意外丟失了2個。

任務調度

介紹

方便的維護一些周期性的任務，例如：在一個下單交易的應用里，超時未支付的訂單需要被關閉掉，就可以通過任務調度模塊添加一個調度任務來每隔 1 分鍾調用一次應用的某接口來讓應用檢查那些超期未支付的訂單。

執行歷史僅保留每個任務最近 50 條記錄，多余的記錄將會被自動刪除。

監控中心

介紹

該模塊提供了以下幾種常用的監控模式

• 站點檢測

通過 GET 請求指定的 url 匹配返回的狀態碼來確定站點是否異常，目前200 - 399之間狀態碼均為正常，否則為異常，默認超時時間為 10 秒。

• 端口檢測

檢測指定目標主機的 TCP 端口是否可以正常建立接連。

• Ping 檢測

（v2.3.10新增）使用 Ping 檢測目標主機是否存活，默認超時時間為 3 秒。

• 進程檢測

檢測指定目標主機的某個進程是否存活。

• 自定義腳本檢測

在指定主機上運行自定義的腳本，通過判斷返回的退出狀態碼是否為 0 來確定是否有異常。腳本執行中輸出的內容將作為報警的描述信息，可利用此特性來靈活控制 報警的規則和報警的內容。

配置說明

• 監控頻率： 每隔多長時間檢測一次
• 報警閾值： 連續指定次數檢測失敗后才會觸發報警，例如：報警閾值設置為3，則表示當出現故障時連續3次檢測都為失敗的情況才觸發報警
• 報警聯系人組： 報警聯系人的集合，可以包含一個或多個報警聯系人
• 通道沉默： 相同的檢測失敗事件在通道沉默周期內只觸發一次報警，避免過於頻繁重復的報警信息。例如：通道沉默設置為 5 分鍾，第一次觸發報警后，5分鍾內再次觸發相同的報警信息則不會發送。
• 報警方式 目前支持微信、釘釘和郵件三種報警方式，內置開箱即用的微信和郵件報警服務，需要關注下方服務號 Spug 獲取調用憑據，將調用憑據配置至系統設置 / 報警服務設置 中的調用憑據中。
• 微信報警，需要設置報警聯系人的微信 Token，獲取方式與獲取調用憑據相同
• 釘釘報警，需要設置報警聯系人的釘釘機器人 URL，請在釘釘群-安全設置里面添加部署服務器的外網 IP，或者設置關鍵字 通知
• 郵件報警，需要設置報警聯系人的郵箱地址

報警中心

報警記錄

介紹

查詢最近30天內的報警記錄。

提示
超過30天的報警記錄會被自動刪除，通道沉默期發送的報警信息不會記錄。

報警聯系人

介紹

用戶維護報警的聯系人相關內容，每種額外信息對應一種報警方式。

小提示

• 微信 Token 的獲取需要關注公眾號Spug 在 我的 菜單中獲取。
• 內置的微信和郵件報警模式需要配置調用憑據，調用憑據的獲取方式與微信 Token 相同，獲取調用憑據后，將調用憑據配置至系統設置 / 報警服務設置 中的調用憑據中即可。
• 調用憑據可以是任何一個有效的微信 Token。
• 由於微信的限制，你必須關注公眾號才能收到微信報警信息。
• 釘釘收不到通知？

報警聯系組

介紹

聯系組即為報警聯系人的組合，在監控中心模塊設置的報警通知對象必須為聯系組。

系統管理

賬戶管理

介紹

除了頁面上對普通用的管理，Spug 還提供了 manage.py user 命令可用於管理員賬戶的管理操作。

創建賬戶

創建賬戶使用 manage.py user add 命令，用法示例如下

cd spug/spug_api
source venv/bin/activate
python manage.py user add -u admin -p 123 -n 張三豐 -s

Docker 安裝的可以執行如下命令

docker exec spug python3 /data/spug/spug_api/manage.py user add -u admin -p 123 -n 張三豐 -s

以上命令會創建個登錄名為 admin 密碼為 123 昵稱為 張三豐 的管理員賬戶，注意最后的 -s 參數，如果攜帶了這個參數意味着該賬戶為管理員賬戶， 管理員賬戶可以不受任何限制的訪問所有功能模塊。

重置密碼

使用 manage.py user reset 命令來重置賬戶密碼，用法示例如下

cd spug/spug_api
source venv/bin/activate
python manage.py user reset -u admin -p abc

Docker 安裝的可以執行如下命令

docker exec spug python3 /data/spug/spug_api/manage.py user reset -u admin -p abc

上述操作會重置登錄名為 admin 的賬戶的密碼為 abc。

啟用賬戶

當頁面上登錄連續錯誤數次超過3次后賬戶自動轉為禁用狀態，普通用戶可以通過 系統管理 / 賬戶管理 在頁面是啟用賬戶即可，但管理員賬戶需要使用如下命令來啟用

cd spug/spug_api
source venv/bin/activate
python manage.py user enable -u admin

Docker 安裝的可以執行如下命令

docker exec spug python3 /data/spug/spug_api/manage.py user enable -u admin

系統設置

介紹

除了頁面上對系統設置的管理，Spug 還提供了 manage.py set 命令可用於通過命令行進行管理操作。

禁用登錄MFA

當某些特殊情況下可通過 manage.py set mfa disable 命令禁用MFA，用法示例如下

cd spug/spug_api
source venv/bin/activate
python manage.py set mfa disable

Docker 安裝的可以執行如下命令

docker exec spug python3 /data/spug/spug_api/manage.py set mfa disable

微信Token

介紹

微信Token 是 Spug 提供內置服務的用戶身份標識，通過該標識與微信用戶建立關聯，提供例如微信告警、登錄兩步驗證等功能。

獲取方法

搜索（或掃描下方的二維碼）關注微信公眾號 Spug。
在公眾號底部的 我的 菜單中獲取微信Token。

用途

• 作為 Spug 內置服務的調用憑據（系統設置/基本設置）。
• 告警模塊中，作為微信告警的用戶標識。
• 當啟用登錄MFA（兩步）認證時，作為發送驗證碼的用戶標識。

小提示

• 同一個 微信Token 可以在不同的模塊中使用。
• 由於微信的限制，你必須關注公眾號才能收到相關信息。

發布模板

Java項目配置

概覽

以 若依管理系統 https://gitee.com/y_project/RuoYi 作為例子，最終大概是這樣子的。

注意
以下基於 spug v2.3.4 版本，如果低於 v2.3.4 可以參考 版本升級文檔 進行升級，例子僅作為演示，一般情況下你都需要結合自己的項目情況調整配置。

安裝 jdk / maven

如果已安裝可跳過該步驟，這里以安裝 jdk-8u251 和 maven-3.6.3 為例，如果你使用 Docker 部署的 Spug，可參考以下步驟進行安裝

注意
以下僅適用於 2.3.4 及以后的鏡像（基於 Centos）啟動的容器（這里的 2.3.4 並不是 Spug 的版本號，請在 hub.docker.com 查詢鏡像版本）。

因 Oracle JDK 下載需要登錄賬戶請自行下載，這里直接使用下載完成的 jdk-8u251-linux-x64.tar.gz 文件。

# 自行至 https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html 下載jdk
# 把已下載的壓縮包拷貝進容器
docker cp jdk-8u251-linux-x64.tar.gz spug:/
docker exec -it spug bash
tar xf jdk-8u251-linux-x64.tar.gz -C /opt

# 安裝maven
curl -o apache-maven-3.6.3-bin.tar.gz http://apache.mirrors.pair.com/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.tar.gz
tar xf apache-maven-3.6.3-bin.tar.gz -C /opt/
echo -e 'export JAVA_HOME=/opt/jdk1.8.0_251\nexport PATH=$PATH:$JAVA_HOME/bin:/opt/apache-maven-3.6.3/bin' > /etc/profile.d/java.sh

# [可選]配置阿里雲鏡像加速下載，在159-164行（<mirrors\>標簽內）添加以下內容
vi /opt/apache-maven-3.6.3/conf/settings.xml

    159     <mirror>
    160       <id>aliyunmaven</id>
    161       <mirrorOf>*</mirrorOf>
    162       <name>阿里雲公共倉庫</name>
    163       <url>https://maven.aliyun.com/repository/public</url>
    164     </mirror>

# 退出並重啟容器
exit
docker restart spug

文件過濾

只需要發布編譯過的 jar 包，所以這里選擇了 包含 規則。

ruoyi-admin.jar

自定義變量

該例子中並不需要特殊的 全局變量，如果你需要的話可以在這里定義，然后在下邊的鈎子中類似 $SPUG_DEPLOY_ID 那樣去引用。

代碼檢出前

該例子中也不需要執行。

代碼檢出后

在這里進行項目的依賴包安裝和編譯工作，該鈎子中當前目錄即為按發布申請中選擇 Git 分支/版本 檢出后的代碼目錄。

# 執行maven編譯
mvn clean package -Dmaven.test.skip=true
cp ruoyi-admin/target/ruoyi-admin.jar .

這里拷貝 ruoyi-admin.jar 至項目根目錄，因為咱們文件過濾規則指定的就是相對於項目根目錄。

應用發布前

發布前停止現有的服務。

# 停止服務
set +e
ps -ef | grep ruoyi-admin | grep -v grep | awk '{print $2}' | xargs kill -9

因為 Spug 會檢測每個鈎子內腳本最終退出狀態碼，如果非 0 則認為執行異常終止發布，所以如果你的目標主機是 Centos 則需要通過 if 來判斷進程 是否存在，如果存在才執行 kill。

# 停止服務
PID=$(ps -ef | grep ruoyi-admin | grep -v grep | awk '{print $2}')
if [ ! -z $PID ]; then
   kill -9 $PID
fi

應用發布后

在這里啟動服務。

# 添加jdk至PATH變量
PATH=$PATH:/usr/local/jdk1.8.0_231/bin
nohup java -jar ruoyi-admin.jar &> run.log &

Node項目配置

概覽

以 Spug 的前端 spug_web 作為例子來說下前端項目的配置，最終大概是這樣子的。

注意
以下基於 spug v2.3.4 版本，如果低於 v2.3.4 可以參考 版本升級文檔 進行升級，例子僅作為演示，一般情況下你都需要結合自己的項目情況調整配置。

安裝 node(npm)

如果已安裝可跳過該步驟，這里以目前的最新版 v12.18.1 為例，如果你使用 Docker 部署的 Spug，可參考以下步驟進行安裝。

注意
以下僅適用於 2.3.4 及以后的鏡像（基於 Centos）啟動的容器（這里的 2.3.4 並不是 Spug 的版本號，請在 hub.docker.com 查詢鏡像版本）。

# 進入容器
docker exec -it spug bash
curl -o node-v12.18.1-linux-x64.tar.xz https://nodejs.org/dist/v12.18.1/node-v12.18.1-linux-x64.tar.xz
tar xf node-v12.18.1-linux-x64.tar.xz -C /opt
echo 'export PATH=$PATH:/opt/node-v12.18.1-linux-x64/bin' > /etc/profile.d/node.sh

# 安裝yarn，推薦使用yarn來代替npm
source /root/.bashrc
npm install -g yarn

# 退出並重啟容器
exit
docker restart spug

文件過濾

前端項目發布的時候只需要編譯后的內容就可以，這里選擇了 包含 條件，內容為 spug_web/build，這樣最終發布到目標主機上的代碼僅包含 spug_web/build，並不會把 spug_api 及 spug_web 中的前端源代碼發布出去。

自定義變量

該例子中並不需要特殊的全局變量，如果你需要的話可以在這里定義，然后在下邊的鈎子中類似 $SPUG_DEPLOY_ID 那樣去引用。

代碼檢出前

作為前端項目免不了要處理項目依賴包的問題，依賴安裝一般在 package.json 所在的目錄（在本示例中即spug_web）中執行 npm install 或 yarn 來安裝。這里使用了 全局環境變量 中的 SPUG_REPOS_DIR 和 SPUG_DEPLOY_ID 來切換到源碼目錄創建公共的 node_modules 目錄，以后每次發布時都通過軟鏈接的形式使用它來避免每次 發布都需要全量安裝依賴包。

# 創建公共node_modules目錄
mkdir -p $SPUG_REPOS_DIR/$SPUG_DEPLOY_ID/node_modules

代碼檢出后

在這里進行項目的依賴包安裝和編譯工作，該鈎子中當前目錄即為按發布申請中選擇 Git 分支/版本 檢出后的代碼目錄，我們需要先把上一步創建的公共 node_modules 目錄鏈接到當前目錄（這樣可以避免每次都完整的執行npm install來重復安裝依賴包），然后執行 yarn build 來進行項目編譯。

# 創建軟鏈接，指向公共的node_modules,避免每次發布重復安裝依賴包
cd spug_web
ln -s $SPUG_REPOS_DIR/$SPUG_DEPLOY_ID/node_modules .
# 執行依賴安裝
yarn
# 執行 編譯
yarn build

編譯后也就生成了我們在 文件過濾 中設置的 spug_web/build 目錄。

應用發布前

由於我們設置的文件過濾規則 spug_web/build，所以傳輸到目標主機上文件結構也是 spug_web/build/xx，我們需要調整下目錄結構， 讓 spug_web/build 目錄下內容放到項目的根目錄中。

# 調整目錄結構，把編譯結果放在項目根目錄
mv spug_web/build/* .
rm -rf spug_web

應用發布后

前端項目編譯后就是純靜態的 html、js 和一些靜態文件，這里一般就不需要額外的處理了。

進階指南

手動部署

注意
我們推薦你使用 Docker安裝 來確保體驗的一致性。

准備環境

• Python 3.6及以上
• Mysql 5.6及以上
• 現代瀏覽器
• 自v2.3.9 開始 Git 版本需要 2.17.0+ （影響新建常規發布申請單）

安裝步驟

以下安裝步驟假設項目部署在一台 Centos7 系統的 /data/spug 目錄下。

1. Clone項目代碼

git clone https://github.com/openspug/spug /data/spug
cd /data/spug
git checkout x.x.x   # x.x.x 為指定的發行版本，例如 git checkout v2.2.2 

2. 下載 已編譯打包后的前端項目
   將下載好的前端壓縮包解壓到指定目錄，假設web_x.y.z.tar.gz 是的你下載好的壓縮包

提示
訪問 Github 比較慢的情況下，可以在嘗試在 Gitee 下載。

tar xf web_x.y.z.tar.gz -C /data/spug/spug_web/;

3. 創建運行環境
   如需要使用常規發布功能，則需要安裝 git v2.17.0+。

# 安裝依賴
yum install mariadb-devel python3-devel gcc openldap-devel redis nginx supervisor

# 創建虛擬環境
cd /data/spug/spug_api
python3 -m venv venv
source venv/bin/activate

# 安裝python包
pip install -U pip -i https://pypi.tuna.tsinghua.edu.cn/simple/
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
pip install gunicorn mysqlclient -i https://pypi.tuna.tsinghua.edu.cn/simple/

4. 修改后端配置
   后端默認使用的 Sqlite 數據庫，通過修改配置使用 MYSQL 作為后端數據庫。

注意
在 spug_api/spug/ 目錄下創建 overrides.py 文件，啟動后端服務后會自動覆蓋默認的配置，避免直接修改 settings.py 以便於后期獲取新版本。

spug_api/spug/overrides.py
DEBUG = False

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.dev -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

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. 訪問測試
    通過瀏覽器訪問測試。

11. 安全建議

• 請確保安裝的 Redis 僅監聽在 127.0.0.1。
• 確保服務端接收到請求 HTTP Header 的 X-Real-IP 為真實的客戶端地址，Spug 會使用該 IP 提高安全性（當登用戶的 IP 發生變化時 Token 自動失效）。

二次開發

此安裝文檔適合具有一定編程能力基礎的人員進行二次開發時的環境搭建，如果你是在生產環境部署，推薦 Docker安裝， 如有必要你也可以考慮 手動部署。

依賴環境

• Python 3.6及以上
• Nodejs 12.14 LTS
• Redis 3.x及以上
• 現代瀏覽器

安裝步驟

以下安裝步驟假設項目安裝在一台 macOS 系統的 /data/spug 目錄下。

1. Clone項目代碼

git clone https://github.com/openspug/spug /data/spug

2. 創建運行環境

cd /data/spug/spug_api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

3. 初始化數據庫
   默認使用的 Sqlite 數據庫。

python manage.py updatedb

4. 創建默認管理員賬戶

python manage.py user add -u admin -p spug.dev -s -n 管理員

# -u 用戶名
# -p 密碼
# -s 超級管理員
# -n 用戶昵稱

5. 啟動 api 開發環境服務

python manage.py runserver

6. 安裝前端依賴
   可以把 npm 用 yarn 或 cnpm 代替。

cd /data/spug/spug_web
npm install --registry=https://registry.npm.taobao.org

7. 啟動前端

npm start

8. 訪問測試
   正常情況下 npm start 會自動在瀏覽器中打開項目，如果未打開可以在瀏覽器中輸入 http://localhost:3000 訪問。
   如果你按照上邊的文檔執行的話，在第 4 步創建了默認的管理員賬戶：

用戶名：admin  
密碼：spug.dev

9. 其他可選服務
   通過以上步驟已經可以正常訪問 Spug 了，但一些功能依賴額外的服務。

實踐指南

安全性實踐指南

寫在前面，沒有絕對的安全，如果環境允許的話盡量把 Spug 部署在內網且禁止公網訪問，如果必須通過公網訪問則盡可能通過防火牆等手段限制指定 IP 訪問。
Spug 在登錄安全方面提供了連續3次錯誤密碼自動禁用賬戶的功能，盡可能的避免了被暴力破解登錄的可能性。在 Token 安全方便提供了基於訪問來源 IP 的 安全策略，當同一個 Token 訪問來源 IP 發生變化時 Token 將自動失效，強制重新登錄（v3.0.2之后可以通過系統設置關閉該特性）。

注意
Token 安全策略中的來源 IP 依賴 Nginx 轉發請求時攜帶的 HTTP 頭 X-Real-IP 和 X-Forwarded-For（v2.3.12+）， 所以請務必確保 Spug 能獲取到用戶的真實 IP 而不是上級的代理 IP，如果你使用的推薦的 Docker 部署方式，則這些工作默認已經做好了。 如果要在 Docker 容器暴露的 80 端口上再增加反向代理層，請正確配置 X-Forwarded-For，例如 Nginx 增加 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;。
在無法驗證訪問者的真實 IP 的情況下（Spug獲取到的IP是內網IP），會在登錄時彈出一個警告信息，如果 Spug 部署在內網且僅在內網使用（通過內網地址訪問 Spug），則可以在 v2.3.14 版本后通過 系統管理 / 系統設置 / 安全設置 / 訪問IP校驗 來關閉這一特性。

發布過程中不同主機執行不同操作

假設一個應用需要發布到不同的三台主機上，但發布需要在主機上執行一些比如更新數據庫等一次性且不能重復執行的操作，這時候可以考慮使用 Spug 的全局變量 SPUG_HOST_ID 或 SPUG_HOST_NAME 來指定只在某個主機上執行這些操作，例如：

if [ "$SPUG_HOST_NAME" = "192.168.10.100" ]; then
    echo "exec sql"
fi

默認PATH環境變量導致命令找不到問題

默認的 PATH 變量可能並不完整，如果出現一些命令找不到等報錯情況可以使用類似如下寫法來解決這個問題：

# 添加jdk至PATH變量
PATH=$PATH:/usr/local/jdk1.8.0_231/bin
java -jar xxx.jar

項目數據的持久存儲

一些項目會在運行過程中生產需要持久存儲的數據，例如用戶上傳的圖片或需要留存的日志文件等。當使用常規發布時每個版本都是全新的目錄，默認情況下這些文件會 在新版本中不可見。這種情況可以考慮把這些動態生成且需要持久存儲的數據放在發布目錄之外，通過軟鏈接的形式鏈接至項目內，這樣實際文件存儲在一個公共的地 方每次更新時只需要額外做一個軟鏈接的映射就可以解決問題了。

命令執行中的報錯處理

從 v3 開始 Spug 移除了 set -e 特性，保持了與默認執行腳本行為一致。 如果你對執行中命令錯誤敏感，例如期望任何一個命令執行失敗則中斷 后續的命令，則可以在你編寫的命令開頭加上 set -e 即可。

使用 su 切換身份執行

默認情況下直接使用 su 命令將會導致執行到該命令時卡住無法繼續執行，可通過如下方式使用 su 以使其正常工作：

su - ubuntu << EOF
echo '以ubuntu用戶身份執行'
EOF