Jumpserver 安裝和升級常見問題

1、安裝過程中常見的問題

1. git clone 提示 ssl 錯誤

# 一般是由於時間不同步, 或者網絡有問題導致的
# 可以嘗試下載 releases 包

2. pip install 提示 ssl 錯誤

# 參考第一條解決

3. pip install 提示 download 錯誤

# 一般是由於網絡不好, 導致下載文件失敗, 重新執行命令即可
# 如果多次重試均無效, 請更換網絡環境

4. pip install 提示 Could not find a version that satisfies the requirement xxxxxx==x.x.xx(版本)

# 一般是由於鏡像源未同步, -i 指定官方源即可, 如：
$ pip install -r requirements.txt -i https://pypi.org/simple
$ pip install xxxxx==x.x.xx -i https://pypi.org/simple

5. pip install 提示 install for mysqlclient ... error /usr/bin/ld: 找不到 -lmariadb

# 如果是 Mariadb 大於 10 版本
$ yum install MariaDB-shared

6. sh make_migrations.sh 時報錯 from config import config as CONFIG File "/opt/jumpserver/config.yml", line 38

# 這是由於 config.yml 里面的內容格式不對, 請參考安裝文檔的說明, 把提示的內容與上一行對齊即可

7. sh make_migrations.sh 時報錯 Are you sure it's installed and available on your PYTHONPATH environment variable? Did you forget to activate a virtual environment?

# 一般是由於 py3 環境未載入
$ source /opt/py3/bin/activate

# 看到下面的提示符代表成功, 以后運行 Jumpserver 都要先運行以上 source 命令, 以下所有命令均在該虛擬環境中運行
(py3) [root@localhost py3]

# 如果已經在 py3 虛擬環境下, 任然報 Are you sure it's installed and available on your PYTHONPATH environment variable? Did you forget to activate a virtual environment?
$ cd /opt/jumpserver/requirements
$ pip install -r requirements.txt
# 然后重新執行 sh make_migrations.sh

8. sh make_migrations.sh 報錯 CommandError: Conflicting migrations detected; multiple ... django_celery_beat ...

# 這是由於 django-celery-beat老版本有bug引起的
$ rm -rf /opt/py3/lib/python3.6/site-packages/django_celery_beat/migrations/
$ pip uninstall django-celery-beat
$ pip install django-celery-beat

9. 執行 ./jms start 后一直卡在 beat: Waking up in 1.00 minute.

# 如果沒有error提示進程無法啟動, 那么這是正常現象
# 如果不想在前台啟動, 可以使用 ./jms start -d 在后台啟動

10. 執行 ./jms start 后提示 xxx is stopped

# Error: xxx start error
# xxx is stopped
$ ./jms restart xxx  # 如 ./jms restart gunicorn

11. 執行 ./jms start 后提示 WARNINGS: ?: (mysql.W002) MySQL Strict Mode is not set for database connection 'default' ...

# 這是嚴格模式的警告, 可以參考后面的url解決, 或者忽略

12. 啟動 Jumpserver 或者 coco 報錯 Error: expected '<document start>', but found '<scalar>'

# 這是因為你的 config.yml 文件格式有誤
# 常見的錯誤就是字段為空或者: 后面有一個空格
# SECRET_KEY: xxxxx  # 不要忽略: 后面的空格

13. 啟動 jumpserver 后, 訪問 8080 端口頁面顯示不正常

# 這是因為你在 config.yml 里面設置了 DEBUG: false
# 跟着教程繼續操作, 后面搭建 nginx 代理即可正常訪問

14. 執行 ./cocod start 后提示 No module named 'jms'

# 一般是由於 py3 環境未載入
$ source /opt/py3/bin/activate

# 看到下面的提示符代表成功, 以后運行 Jumpserver 都要先運行以上 source 命令, 以下所有命令均在該虛擬環境中運行
(py3) [root@localhost py3]

# 如果已經在 py3 虛擬環境下
$ cd /opt/coco/
$ pip install -r requirements/requirements.txt
# 然后重新執行 ./cocod start 即可

15. 執行 ./cocod start 后提示 Failed register terminal xxxx exist already

# 這是由於 coco 注冊未成功造成的, 需要重新注冊 (能正常訪問 jumpserver 頁面后再處理)
# 到 Jumpserver后台 會話管理-終端管理  刪掉 coco 的注冊
# 必須到 Jumpserver后台 會話管理-終端管理  刪掉 coco 的注冊
# 一定要先到 Jumpserver后台 會話管理-終端管理  刪掉 coco 的注冊
$ cd /opt/coco && ./cocod stop
$ rm /opt/coco/data/keys/.access_key  # coco, 如果你是按文檔安裝的, key應該在這里, 如果不存在key文件直接下一步
$ ./cocod start -d  # 正常運行后到Jumpserver 會話管理-終端管理 里面接受coco注冊

16. 執行 ./cocod start 后提示 Failed register terminal unknow: xxxx

# 這是因為當前系統的 hostname 有 coco 不支持的字符, 需要手動指定 coco 的 NAME
$ cd /opt/coco/
$ vi config.yml

# 項目名稱, 會用來向Jumpserver注冊, 識別而已, 不能重復
# NAME: {{ Hostname }}
NAME: localhost

# 保存后重新執行 ./cocod start 即可

17. 運行 ./cocod start 后提示 "detail":"身份認證信息未提供。" Failed register terminal

# 保證 coco 的 BOOTSTRAP_TOKEN 與 jumpserver/config.yml 里面的內容不一致
$ cat /opt/jumpserver/config.yml | grep BOOTSTRAP_TOKEN
$ cat /opt/coco/config.yml | grep BOOTSTRAP_TOKEN

# 修改成一致保存后 重新執行 ./cocod start 即可

18. 運行 ./cocod start 后提示 Connect endpoint http://xxxx:8080 error: HTTPConnectionPool(host='xxxx', port=8080)

# 這是因為 coco 無法連接到 jumpserver 報的錯誤, 確定 http://xxxx:8080 設置正確(配置文件 coco/config.yml)
# 如果 jumpserver 的IP和端口不對, 請手動修改 config.yml 的 CORE_HOST

19. 運行 ./cocod start 后提示 Unexpected error occur: 'AppService' object has no attribute 'get_system_user_cmd_filter_rules'

# 這是因為你的 pip 依賴包未正確安裝, 參考本文檔第 4 條

20. 通過 nginx 代理的端口訪問 jumpserver 頁面顯示不正常

# 這是因為你沒有按照教程進行安裝, 修改了安裝目錄, 需要在 nginx 的配置文件里面修改資源路徑
$ vi /etc/nginx/conf.d/jumpserver.conf

...

server {
    listen 80;  # 代理端口, 以后將通過此端口進行訪問, 不再通過8080端口

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    location /luna/ {
        try_files $uri / /index.html;
        alias /opt/luna/;  # luna 路徑, 如果修改安裝目錄, 此處需要修改
    }

    location /media/ {
        add_header Content-Encoding gzip;
        root /opt/jumpserver/data/;  # 錄像位置, 如果修改安裝目錄, 此處需要修改
    }

    location /static/ {
        root /opt/jumpserver/data/;  # 靜態資源, 如果修改安裝目錄, 此處需要修改
    }

    location /socket.io/ {
        proxy_pass       http://localhost:5000/socket.io/;  # 如果coco安裝在別的服務器, 請填寫它的ip
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /coco/ {
        proxy_pass       http://localhost:5000/coco/;  # 如果coco安裝在別的服務器, 請填寫它的ip
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        access_log off;
    }

    location /guacamole/ {
        proxy_pass       http://localhost:8081/;  # 如果guacamole安裝在別的服務器, 請填寫它的ip
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        access_log off;
        client_max_body_size 100m;  # Windows 文件上傳大小限制
    }

    location / {
        proxy_pass http://localhost:8080;  # 如果jumpserver安裝在別的服務器, 請填寫它的ip
    }
}

...

21. 訪問 luna 頁面提示 Luna是單獨部署的一個程序, 你需要部署luna, coco, 配置nginx做url分發...

# 請通過 nginx 代理的端口訪問 jumpserver 頁面, 不要再直接訪問 8080 端口

---

2、升級常見問題

請務必認真詳細閱讀每一個文字並理解后才能操作升級事宜

1. git pull 時提示 error: Your local changes to the following file would be overwritten by merge

# 這是因為你修改了本地文件導致代碼沖突, 請確認修改的內容並手動進行合並, 請謹慎處理

# 如果希望保留你的改動
$ git stash
$ git pull
$ git stash pop
# 可以使用git diff -w +文件名 來確認代碼自動合並的情況

# 或者放棄本地的修改
$ git reset --hard
$ git pull

2. sh make_migrations.sh 時提示 1064, "You have an error in your SQL syntax; check the manual than corresponds to your MySql server version for the right syntax to use near '(6) NOT NULL'"

# 這是因為你的數據庫版本不對, 從 1.4.x 版本開始 mysql 版本需要大於等於 5.6, mariadb 版本需要大於等於 5.5.6
# 請更換數據庫重新操作

3. 數據庫表結構不完整導致升級失敗的, 按如下內容進行處理

# 一定要知道自己升級之前的版本, 在升級之前可以通過如下代碼進行查詢, 記住是升級之前, 也可以通過 web 頁面的右下角來查看當前版本信息
$ cat /opt/jumpserver/apps/jumpserver/context_processor.py | grep version
$ cat /opt/jumpserver/apps/templates/_footer.html | grep Version

# 備份當前版本數據庫, 忽略 django_migrations 表
$ mysqldump -uroot -p jumpserver --ignore-table=jumpserver.django_migrations > /opt/jumpserver.sql

# 重命名 Jumpserver 目錄
$ mv /opt/jumpserver /opt/jumpserver_bak

# 重新 clone 代碼
$ cd /opt
$ git clone https://github.com/jumpserver/jumpserver.git
$ cd jumpserver

# 檢出你之前的版本, 比如之前的版本是1.4.0
$ git checkout 1.4.0  # 1.4.0 表示版本號, 自己手動更換成你當前的版本, 如 1.3.1 則輸入 git checkout 1.3.1

# 依賴安裝
$ source /opt/py3/bin/activate
$ yum -y install $(cat /opt/jumpserver/requirements/rpm_requirements.txt)
$ pip install wheel
$ pip install -r /opt/jumpserver/requirements/requirements.txt

# 重新創建一個數據庫
$ mysql -uroot
> create database jumpserver01 default charset 'utf8';
> grant all on jumpserver01.* to 'jumpserver01'@'127.0.0.1' identified by 'weakPassword';
> flush privileges;
> quit

# 修改配置文件
$ cp /opt/jumpserver_bak/config.py /opt/jumpserver/
$ vim /opt/jumpserver/config.py
DB_ENGINE = 'mysql'
DB_HOST = '127.0.0.1'
DB_PORT = 3306
DB_USER = 'jumpserver01'
DB_PASSWORD = 'weakPassword'
DB_NAME = 'jumpserver01'

# 初始化數據庫
$ cd /opt/jumpserver/utils
$ sh make_migrations.sh

# 確定初始化沒有錯誤, 把舊的數據庫導入
$ mysql -uroot
> use jumpserver01;
> source /opt/jumpserver.sql

# 啟動 jumpserver, 確定沒有錯誤
$ cd /opt/jumpserver
$ ./jms start

# 打開 web 頁面檢查是否都正常

$ 參考升級文檔繼續升級到最新版本即可

# 刪除原數據庫命令(謹慎操作)
$ mysql -uroot
> drop database jumpserver;
> quit