confluence 4.2 升級至 6.10.x 記錄

confluence 4.2 升級至 6.10.x 記錄

首先將線上環境中的 confluence 安裝目錄、資料目錄以及資料庫進行備份，相關資訊如下：

• 安裝目錄：/opt/atlassian/confluence
• 資料目錄：/opt/confluencedata
• 資料庫：confluence_smc

具體升級過程如下：

一、修改 confluence 服務應用程式目錄

由於公司 confluence 服務 4.2 版本安裝時，將應用程式目錄移動至 webapps 目錄下，導致升級時會無法識別到安裝路徑，所以需要修改應用程式路徑，步驟如下：

首先停止 confluence 服務，將 webapps 目錄下的 wiki 目錄移動到安裝目錄的根目錄下，並重新命名為 confluence：

mv /opt/atlassian/confluence/webapps/wiki /opt/atlassian/confluence/confluence

修改 server.xml 檔案，將 docBase 修改為如下內容：

<Context path="" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">

修改完成後重新啟動 confluence 服務驗證訪問，此時直接輸入 IP:埠 即可

/opt/atlassian/confluence/bin/startup.sh

二、修改資料庫配置

1. 修改字符集和排序

由於公司當前使用的 confluence 服務的資料庫字符集為 utf8，並且未指定排序方式。為了保證後面跨版本升級時新的資料庫結構能夠正常同步，首先需要對資料庫中的預設字符集和排序方式進行修改，修改步驟如下：

1. 由於涉及修改的資料量比較大，首先設定忽略外來鍵約束，避免修改時報錯：

SET FOREIGN_KEY_CHECKS=0;

2. 修改資料庫預設字符集和排序，命令如下：

ALTER DATABASE confluence_smc CHARACTER SET utf8 COLLATE utf8_bin;

3. 修改資料庫中所有表的字符集和排序，命令如下：

SELECT CONCAT('ALTER TABLE `',  table_name, '` CHARACTER SET utf8 COLLATE utf8_bin;')
FROM information_schema.TABLES AS T, information_schema.`COLLATION_CHARACTER_SET_APPLICABILITY` AS C
WHERE C.collation_name = T.table_collation
AND T.table_schema = 'confluence_smc'
AND
(
    C.CHARACTER_SET_NAME != 'utf8'
    OR
    C.COLLATION_NAME != 'utf8_bin'
);

上面的命令執行完成後會生成修改所有表的 sql 語句，將這些 sql 複製到資料庫內執行即可完成修改

4. 修改所有資料型別為 varchar 欄位的字符集和排序：

SELECT CONCAT('ALTER TABLE `', table_name, '` MODIFY `', column_name, '` ', DATA_TYPE, '(', CHARACTER_MAXIMUM_LENGTH, ') CHARACTER SET utf8 COLLATE utf8_bin', (CASE WHEN IS_NULLABLE = 'NO' THEN ' NOT NULL' ELSE '' END), ';')
FROM information_schema.COLUMNS 
WHERE TABLE_SCHEMA = 'confluence_smc'
AND DATA_TYPE = 'varchar'
AND
(
    CHARACTER_SET_NAME != 'utf8'
    OR
    COLLATION_NAME != 'utf8_bin'
);

上面的命令執行完成後會生成修改所有相關欄位的 sql 語句，將這些 sql 複製到資料庫內執行即可完成修改

5. 修改所有資料型別不是 varchar 欄位字符集和排序：

SELECT CONCAT('ALTER TABLE `', table_name, '` MODIFY `', column_name, '` ', DATA_TYPE, ' CHARACTER SET utf8 COLLATE utf8_bin', (CASE WHEN IS_NULLABLE = 'NO' THEN ' NOT NULL' ELSE '' END), ';')
FROM information_schema.COLUMNS 
WHERE TABLE_SCHEMA = 'confluence_smc'
AND DATA_TYPE != 'varchar'
AND
(
    CHARACTER_SET_NAME != 'utf8'
    OR
    COLLATION_NAME != 'utf8_bin'
);

上面的命令執行完成後會生成修改所有相關欄位的 sql 語句，將這些 sql 複製到資料庫內執行即可完成修改

6. 設定開啟外來鍵約束：

SET FOREIGN_KEY_CHECKS=1;

2. 修改資料庫配置檔案

檢查資料庫的配置檔案，在 [mysqld] 下面新增如下配置項：

character-set-server=utf8
collation-server=utf8_bin
default-storage-engine=INNODB
max_allowed_packet=256M
max_connections=1000
innodb_log_file_size=2GB
transaction-isolation=READ-COMMITTED
binlog_format=row

如果當前資料庫中只有 confluence 一個業務，可以參考如上配置，如果有其他業務共用，為了避免影響其他業務，可以考慮將字符集和引擎設定忽略（可在程式連線資料庫時在 jdbc 連線中指定）。

如果資料庫配置檔案中有如下配置，需要將其刪除，否則會引發報錯。如果還開啟了其他的 sql_mode ，只需要刪除 NO_AUTO_VALUE_ON_ZERO 即可：

sql_mode = NO_AUTO_VALUE_ON_ZERO

如果開啟了 NO_AUTO_VALUE_ON_ZERO 則會引發如下報錯內容：

2020-08-14 09:26:06,520 ERROR [http-8090-4] [atlassian.event.internal.EventPublisherImpl] invokeListeners There was an exception thrown trying to dispatch event 'com.atlassian.confluence.event.events.content.comment.CommentCreateEvent[source=com.atlassian.confluence.pages.DefaultCommentManager@4b077b33]' from the invoker 'com.atlassian.event.internal.SingleParameterMethodListenerInvoker@25695aa2'.
 -- url: /rest/tinymce/1/content/524379/comment | userName: admin| referer: http://<confluence-url>/pages/viewpage.action?pageId=524379
java.lang.RuntimeException: java.lang.reflect.UndeclaredThrowableException
        at com.atlassian.event.internal.SingleParameterMethodListenerInvoker.invoke(SingleParameterMethodListenerInvoker.java:50)
        at com.atlassian.event.internal.AsynchronousAbleEventDispatcher$2.run(AsynchronousAbleEventDispatcher.java:60)
        at com.atlassian.event.internal.AsynchronousAbleEventDispatcher$1.execute(AsynchronousAbleEventDispatcher.java:28)
.....
Caused by: java.lang.reflect.UndeclaredThrowableException
        at $Proxy943.createOrUpdate(Unknown Source)
        at sun.reflect.GeneratedMethodAccessor1033.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
.....
Caused by: java.lang.reflect.InvocationTargetException
        at sun.reflect.GeneratedMethodAccessor1033.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
        at java.lang.reflect.Method.invoke(Unknown Source)
        at com.atlassian.mywork.client.service.ServiceSelectorImpl$3.invoke(ServiceSelectorImpl.java:144)
        ... 235 more
Caused by: java.lang.NullPointerException
        at net.java.ao.EntityManager$CacheKey.hashCode(EntityManager.java:1070)
        at java.util.HashMap.getEntry(Unknown Source)
        at java.util.LinkedHashMap.get(Unknown Source)
        at net.java.ao.EntityManager.getFromCache(EntityManager.java:247)
        at net.java.ao.EntityManager.peer(EntityManager.java:234)
        at net.java.ao.EntityManager.peer(EntityManager.java:299)
        at net.java.ao.EntityManager.create(EntityManager.java:411)
......

配置完成後重啟資料庫服務。

3. 修改 confluence 資料庫配置檔案

confluence 資料庫配置檔案儲存在 confluence 家目錄下，檔名稱為 confluence.cfg.xml，將其中的 hibernate.connection.url 配置項進行修改：

<property name="hibernate.connection.url">jdbc:mysql://IP:3306/confluence_smc?sessionVariables=storage_engine%3DInnoDB</property>

<!--  將以上內容修改為如下（ 新增&amp;useUnicode=true&amp;characterEncoding=utf8 ）-->
<!--  新增這部分內容是由於資料庫中字符集和排序已經修改為 utf8，如果不新增這部分配置會導致升級 5.x 版本時無法同步新的資料庫結構，導致表缺失 -->

<property name="hibernate.connection.url">jdbc:mysql://IP:3306/confluence_smc?sessionVariables=storage_engine%3DInnoDB&amp;useUnicode=true&amp;characterEncoding=utf8</property>

需要注意的是，如果使用 mysql 5.7 版本，也需要將其中的 storage_engine 修改為 default_storage_engine

三、升級至 confluence 4.3.7 版本

confluence 4.X 中能升級的最大版本是 v4.3.7，所以先將 wiki 升級至 4.3.7 版本，步驟如下：

將原 wiki 服務程式停止，下載 4.3.7 版本安裝包至 /opt 目錄下，下載連結：https://www.atlassian.com/software/confluence/downloads/binary/atlassian-confluence-4.3.7-x64.bin

執行該二進位制檔案進行升級：

[root@localhost opt]# ./atlassian-confluence-4.3.7-x64.bin
Unpacking JRE ...
Starting Installer ...

This will install Confluence 4.3.7 on your computer.
OK [o, Enter], Cancel [c]

Choose the appropriate installation or upgrade option.
Please choose one of the following:
Express Install (uses default settings) [1], Custom Install (recommended for advanced users) [2], Upgrade an existing Confluence installation [3, Enter]							# 選擇升級 confluence

Existing installation directory:
[/opt/atlassian/confluence]						   # 指定 confluence 的安裝路徑

Back Up Confluence Home
The upgrade process will automatically back up your Confluence Installation
Directory. You can also choose to back up your existing Confluence Home
Directory. Both directories are backed up as zip archive files in their
respective parent directory locations.

We strongly recommend choosing this option in the unlikely event that you
experience problems with the upgrade and may require these backups to
restore your existing Confluence installation.

If you have many attachments in your Confluence Home Directory, the zip
archive of this directory may consume a significant amount of disk space.
Back up Confluence home ?
Yes [y, Enter], No [n]							 # 備份 confluence 的家目錄，如果此前已經做過備份，此處可選擇 No
n

Checking for local modifications.

List of modifications made within Confluence directories.

The following provides a list of file modifications within the confluence
directory.

Modified files:
	confluence/WEB-INF/lib/atlassian-extras-2.4.jar
Removed files:
	(none)
Added files:
	(none)

[Enter]


Checking if your instance of Confluence is running
Upgrade Check List
Back up your external database
We strongly recommend you back up your Confluence database if you have not
already done so.

Please refer to the following URL for back up guidelines:
http://docs.atlassian.com/confluence/docs-43/Production+Backup+Strategy

Check plugin compatibility
Check that your non-bundled plugins are compatible with Confluence 4.3.7.

For more information see our documentation at the following URL:
http://docs.atlassian.com/confluence/docs-43/Installing+and+Configuring+Plugins+using+the+Universal+Plugin+Manager


Please ensure you have read the above checklist before upgrading.
Your existing Confluence installation is about to be upgraded! Do you want to proceed?
Upgrade [u, Enter], Exit [e]


Your instance of Confluence is currently being upgraded.
Checking if Confluence has been shutdown...
Backing up the Confluence installation directory

Deleting the previous Confluence installation directory...

Extracting files ...


Please wait a few moments while Confluence starts up.
Launching Confluence ...
Installation of Confluence 4.3.7 is complete
Your installation of Confluence 4.3.7 is now ready and can be accessed via
your browser.
Custom modifications
Your previous Confluence installation contains customisations that must be
manually transferred. Refer to our documentation more information:
http://docs.atlassian.com/confluence/docs-43/Upgrading+Confluence#UpgradingConfluence-custommodifications
Confluence 4.3.7 can be accessed at http://localhost:8090

Confluence 4.3.7 may take several minutes to load on first start up.
Finishing installation ...

啟動完成後訪問頁面，如果頁面正常訪問且資料完整，則升級完成（在啟動之前其實還涉及到啟用的過程，這部分之前在博文寫了，但是為了避免引起不必要的麻煩已經刪除，有需要的朋友可以給我留言）。

四、升級至 5.10.9 版本

升級至 4.3.7 版本後，就可以直接升級至 5.10.9 版本，5.10.9 版本下載連結：https://www.atlassian.com/software/confluence/downloads/binary/atlassian-confluence-5.10.9-x64.bin

將下載後的安裝包上傳到 /opt 目錄下，停止 wiki 服務，按照升級 4.3.7 的方式執行升級程式。

如果在執行升級程式時，報如下錯誤：

Could not display the GUI. This application needs access to an X Server.

這代表系統中缺少 dejavu-sans-fonts 軟體包，使用如下命令安裝即可：

yum install -y dejavu-sans-fonts

啟動完成後訪問頁面，如果頁面正常訪問且資料完整，則升級完成（在啟動之前其實還涉及到啟用的過程，這部分之前在博文寫了，但是為了避免引起不必要的麻煩已經刪除，有需要的朋友可以給我留言）。

五、升級至 6.15.9 版本

6.15.9 版本下載連結：https://www.atlassian.com/software/confluence/downloads/binary/atlassian-confluence-6.15.9-x64.bin

將下載後的安裝包上傳到 /opt 目錄下，停止 wiki 服務，按照升級 5.10.9 的方式執行升級程式。

啟動完成後訪問頁面，如果頁面正常訪問且資料完整，則升級完成（在啟動之前其實還涉及到啟用的過程，這部分之前在博文寫了，但是為了避免引起不必要的麻煩已經刪除，有需要的朋友可以給我留言）。

六、修改訪問路徑

原 confluence 將程式主目錄放置在 /opt/atlassian/confluence/webapps 目錄下，而新的 confluence 服務的程式主目錄是在 /opt/atlassian/confluence 目錄下，所以為了確保升級前的連結地址可以正常訪問升級後的服務，需要做如下修改：

1. 將 /opt/atlassian/confluence 目錄下的 confluence 主程式目錄移動至 /opt/atlassian/confluence/webapps 目錄下，並重新命名為 wiki

2. 修改 /opt/atlassian/confluence/conf 目錄下的 server.xml 檔案，將其中指定程式主目錄的配置進行修改：

<Context path="" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
    
<!-- 將上面的配置修改為如下內容 -->
    
<Context path="" docBase="" debug="0" reloadable="false" useHttpOnly="true">
    
<!-- 配置 docBase 部分為空，tomcat 啟動時會自動到 webapps 目錄下尋找專案啟動 -->

3. 重啟 confluence 服務，此時就可以使用原訪問地址http://ops.wiki.com/wiki 進行訪問。

七、處理預覽檔案顯示亂碼的問題

官方處理文件：https://confluence.atlassian.com/confkb/the-text-in-a-powerpoint-excel-or-word-document-looks-different-when-using-the-viewfile-macro-200213562.html#TheTextinaPowerPoint,ExcelorWordDocumentisMissingorLooksDifferentwhenUsingtheViewfileMacro-InstallingMicrosoftFonts

confluence 6 版本新增了檔案預覽的功能，如果系統中缺少字符集，預覽的時候會顯示亂碼，解決辦法如下：

首先在作業系統中建立如下目錄（CentOS 系統）：

mkdir -p /usr/share/fonts/msttcore/

找一臺 Windows 系統的電腦，將 C:\Windows\Fonts 目錄下的所有字型檔案打包，上傳到 /usr/share/fonts/msttcore 目錄下。

在 /opt/atlassian/confluence/bin 目錄下（安裝目錄），編輯 setenv.sh 指令碼，在 CATALINA_OPTS 部分新增如下內容：

CATALINA_OPTS="-Dconfluence.document.conversion.fontpath=/usr/share/fonts/msttcore/ ${CATALINA_OPTS}"

在 /opt/confluencedata 目錄下刪除如下內容（資料目錄）：

rm -rf /opt/confluencedata/viewfile/*
rm -rf /opt/confluencedata/thumbnails/*
rm -rf /opt/confluencedata/shared-home/dcl-document/*
rm -rf /opt/confluencedata/shared-home/dcl-document_hd/*
rm -rf /opt/confluencedata/shared-home/dcl-thumbnail/*

重啟 confluence 服務即可。

八、處理驗證碼不顯示的問題

confluence 預設在登入失敗超過 3 次就會開啟驗證碼認證，如果出現驗證碼完全不顯示，有可能是字元編碼的問題，一般日誌中會有如下報錯：

2020-09-05 15:01:27,053 ERROR [http-8090-1] [[Standalone].[localhost].[/].[jcaptcha]] log Servlet.service() for servlet jcaptcha threw exception
com.octo.captcha.CaptchaException: word is too tall: try to use less letters, smaller font or bigger background:  text bounds = {text=tasble

在 /opt/atlassian/confluence/bin 目錄下（安裝目錄），編輯 setenv.sh 指令碼，在 CATALINA_OPTS 部分新增如下內容：

 CATALINA_OPTS="-Dfile.encoding=UTF-8"

在系統中安裝如下軟體（一般情況下都是預設安裝好的）：

yum -y install deja*

重啟 confluence 即可。

如果只是部分驗證碼不顯示（重新整理多次，偶現驗證不顯示的情況），可能是由於缺失字型導致的，暫未找到解決辦法，可以先關閉驗證碼功能。

九、處理升級 confluence 後無法建立頁面的問題

官方處理文件：

• https://www.cwiki.us/display/CONFLUENCEWIKI/Administering+Collaborative+Editing
• https://www.cwiki.us/display/CONFLUENCEWIKI/Running+Confluence+behind+NGINX+with+SSL

confluence 升級至 6.15.10 版本後，建立空間或頁面會顯示如下報錯：

該檔案的載入時間比平時要長。請稍等片刻，然後嘗試重新整理

頁面會一直卡在重新整理的介面中，經過排查，可以確定是由於 confluence 新增的協同編輯功能導致的。

協同編輯是通過 Synchrony 進行的，Synchrony 在預設的情況下是執行在 8091 埠的。這個能夠實時的同步資料。Synchrony 是一個可執行的程式，這個程式是在 Confluence 之外執行的，但是又是由 Confluence 自動進行管理的。

如果沒有在 confluence 中使用反向代理 ，那麼會通過 Confluence 的內部 Synchrony 代理連線到 Synchrony。

如果 confluence 是執行在一個反向代理的後面的，那麼就需要在反向代理中新增針對 Synchrony 服務 ws 請求的代理配置。例如當前使用 NGINX 作為反向代理，那麼在 NGINX 中新增如下配置（與 confluence 在同一個 server 段）：

location /synchrony {
		proxy_set_header X-Forwarded-Host $host;
		proxy_set_header X-Forwarded-Server $host;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_pass http://IP:8091/synchrony;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "Upgrade";
}

接下來修改 /opt/atlassian/confluence/conf 目錄下的 server.xml 檔案，在其中配置 tomcat 聯結器：

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
		   maxThreads="48" minSpareThreads="10"
		   enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
		   protocol="org.apache.coyote.http11.Http11NioProtocol"
		   proxyName="ops.wiki.com" proxyPort="80" schema="http"/>

修改完成後重啟 confluence 服務即可。

或者直接在 confluence 的設定中將協同編輯功能關閉，也可以解決該問題。