支持特性

• 支持豐富的數據源，包括本地文件、七牛云Kodo、百度BOS、Amazon S3、Azure Blob、又拍云USS、騰訊云COS、金山KS3、HTTP或HTTPS URL列表、阿里云OSS等，并可根據需要擴展。

• 支持單機模式和分布式模式。單機模式部署簡單，使用方便，分布式模式適合大規模數據遷移。

  說明

  單機模式下一次只能遷移一個Bucket。

• 支持斷點續傳。

• 支持流量控制。

• 支持遷移指定時間以后的文件、特定前綴的文件。

• 支持并發數據下載和上傳。

計費說明

ossimport工具本身不收費。在公有云情況下，數據源可能會產生公網流出流量、請求等費用，目的端為OSS會產生請求費用等。如果OSS開通和使用了傳輸加速，還會產生傳輸加速的費用。

注意事項

• 遷移速度

  ossimport遷移速度取決于源端的讀取帶寬、本地網絡帶寬、文件大小等因素。對于小于200 KB文件的遷移，因IOPS使用率高的原因，可能會導致遷移較慢的問題。

• 源端數據為歸檔類型

  通過ossimport遷移數據時，如果源端數據為歸檔類型，您需要對這部分數據解凍完成后再進行遷移。

• 本地中轉

  通過ossimport遷移數據時，數據流會經過本地內存中轉后再上傳至目的端。

• 保留源端數據

  通過ossimport遷移數據時，僅對源端數據執行讀取操作，不對源端數據進行修改和刪除。

• 其他遷移工具（ossutil）

  對于遷移小于30 TB的數據，推薦使用ossutil。該工具簡單方便，通過-u，--update和--snapshot-path選項還可以實現文件的增量遷移，詳細說明請參見cp。

運行環境

部署方式選擇

ossimport有單機模式和分布式模式兩種部署方式。

• 單機模式：當您需要遷移的數據小于30 TB時，推薦部署單機模式。您可以將ossimport部署在任意一臺可以訪問您待遷移數據，且可以訪問OSS的機器上。

• 分布式模式：當您需要遷移的數據大于30 TB時，推薦部署分布式模式。您可以將ossimport部署在任意多臺可以訪問您待遷移數據，且可以訪問OSS的機器上。

  說明

  當您待遷移的數據過大時，為了節約時間，您可以將ossimport部署到與您OSS相同地域的ECS實例上，并通過專線將源數據存放的服務器掛載到阿里云VPC網絡中。多臺ECS實例將數據通過內網遷移至OSS，會極大的提升數據遷移效率。

  您也可以使用ossimport通過公網傳輸，傳輸速度受您本地服務器的帶寬影響。

單機模式

Master、Worker、Tracker、Console運行在一臺機器上，統一打包成ossimport2.jar。系統中有且只有一個Worker。

ossimport
├── bin
│ └── ossimport2.jar  # 包括Master、Worker、Tracker、Console四個模塊的總jar
├── conf
│ ├── local_job.cfg   # 單機Job配置文件
│ └── sys.properties  # 系統運行參數配置文件
├── console.bat         # Windows命令行，可以分布執行調入任務
├── console.sh          # Linux命令行，可以分布執行調入任務
├── import.bat          # Windows一鍵導入，執行配置文件為conf/local_job.cfg配置的數據遷移任務，包括啟動、遷移、校驗、重試
├── import.sh           # Linux一鍵導入，執行配置文件為conf/local_job.cfg配置的數據遷移任務，包括啟動、遷移、校驗、重試
├── logs                # 日志目錄
└── README.md           # 說明文檔，強烈建議使用前仔細閱讀

分布式模式

Master --------- Job --------- Console
    |
    |
   TaskTracker
    |_____________________
    |Task     | Task      | Task
    |         |           |
Worker      Worker      Worker

分布式模式下可以啟動多臺機器執行數據遷移，每臺機器上只能啟動一個Worker。Task平均分配到Worker上執行，一個Worker執行多個Task。

ossimport
├── bin
│ ├── console.jar     # Console模塊jar包
│ ├── master.jar      # Master模塊jar包
│ ├── tracker.jar     # Tracker模塊jar包
│ └── worker.jar      # Worker模塊jar包
├── conf
│ ├── job.cfg         # Job配置文件模板
│ ├── sys.properties  # 系統運行參數配置文件
│ └── workers         # Worker列表
├── console.sh          # 命令行工具，目前支持只Linux
├── logs                # 日志目錄
└── README.md           # 說明文檔，強烈建議使用前仔細閱讀

配置文件

單機模式下有兩個配置文件sys.properties、local_job.cfg，分布式模式下有三個配置文件sys.properties、job.cfg、workers。其中local_job.cfg和job.cfg的配置項是完全一樣的，只是名稱不一樣，workers是分布式環境特有的。

• sys.properties：系統運行參數

  參數	含義	說明
  workingDir	工作目錄	工具包解壓后的目錄。單機模式下請不要修改此參數，分布式模式下每個機器的工作目錄必須相同。
  workerUser	Worker機器的ssh用戶名	如果配置了privateKeyFile ，則優先使用privateKeyFile。 如果沒有配置privateKeyFile，則使用workerUser/workerPassword。 單機模式不需要修改此參數。
  workerPassword	Worker機器的ssh用戶密碼	單機模式不需要修改此參數。
  privateKeyFile	private key文件路徑	如果已經打通了ssh通道，則可以指定此參數，否則為空。 如果配置了privateKeyFile，則優先使用privateKeyFile。 如果沒有配置privateKeyFile，則使用workerUser/workerPassword。 單機模式不需要修改此參數。
  sshPort	ssh端口	默認22，一般情況無需更改。 單機模式不需要修改此參數。
  workerTaskThreadNum	Worker執行Task的最大線程數	該參數與機器的內存/網絡有關，建議值60 。 物理機可以適當加大，例如150 。如果網絡帶寬已占滿，請不要再加大。 如果網絡較差，請適當降低，例如30。防止請求競爭網絡造成大量請求超時。
  workerMaxThroughput(KB/s)	worker數據遷移的流量上限	該值能起到限流作用，默認0表示不限流。
  dispatcherThreadNum	Tracker的Task分發與狀態確認的線程數	默認值一般夠用，沒有特殊需要請不要修改默認值。
  workerAbortWhenUncatchedException	表示遇到未知錯誤時是跳過還是終止	默認跳過。
  workerRecordMd5	在OSS中是否使用元數據x-oss-meta-md5記錄遷移文件的MD5值，默認不記錄。	主要用于用戶使用MD5校驗文件數據。

• job.cfg：數據遷移任務配置，local_job.cfg和job.cfg的配置項是完全一樣的，只是名稱不一樣。

  參數	含義	說明
  jobName	任務名字，字符串。	任務的唯一標識，命名規則 [a-zA-Z0-9_-]{4,128}，支持提交多個名字不同的任務。 如果重復提交同名任務會提示任務已存在，清理（clean）同名任務前， 無法提交同名任務。
  jobType	任務類型，字符串	默認為 import。
  isIncremental	是否打開增量遷移模式，布爾類型。	默認值false。 如果設為true，會每間隔incrementalModeInterval（單位秒）重新掃描一次增量數據，并將增量數據遷移到OSS。
  incrementalModeInterval	增量模式下的同步間隔，整型，單位秒。	isIncremental=true時有效?？膳渲玫淖钚￠g隔為900秒，不建議配置成小于3600秒的值，會浪費大量請求，造成額外的系統開銷。
  importSince	遷移大于該時間的數據，整型，單位秒。	該時間為 Unix時間戳，即自1970年1月1日UTC零點以來的秒數，通過命令date +%s獲取。 默認為0，表示遷移全部數據。
  srcType	同步源類型，字符串， 請注意大小寫。	支持以下類型： local：從本地文件遷移數據到OSS，該選項只需要填寫srcPrefix， 不需要填寫srcAccessKey，srcSecretKey，srcDomain，srcBucket。 oss：從一個 OSS bucket 遷移到另一個 bucket。 qiniu：從七牛云存儲遷移到OSS。 bos：從百度的云存儲遷移到OSS。 ks3：從金山云存儲遷移到OSS。 s3：從 Amazon S3遷移到OSS。 youpai：從又拍云遷移到OSS。 http：通過提供的HTTP或者HTTPS鏈接列表遷移數據到OSS。 cos：從騰訊云存儲COS遷移到OSS。 azure：從Azure Blob遷移到OSS。
  srcAccessKey	源AccessKey，字符串。	如果srcType設置為oss、qiniu、baidu、ks3、s3，則填寫數據源的AccessKey。 如果srcType設置為local、http，則該項不需要填寫。 如果srcType設置為youpai、azure，則填寫用戶名AccountName。
  srcSecretKey	源SecretKey，字符串。	如果srcType設置為oss、qiniu、baidu、ks3、s3，則填寫數據源的 SecretKey。 如果srcType設置為local、http，則該項不需要填寫。 如果srcType設置為youpai，則填寫操作員密碼。 如果srcType設置為azure，則填寫AccountKey。
  srcDomain	源Endpoint	如果srcType設置為local、http，則該項不需要填寫。 如果srcType設置為oss，則填寫從控制臺獲取的域名，非帶bucket前綴的二級域名。 如果srcType設置為qiniu，則填寫從七牛控制臺獲取的對應bucket的域名。 如果srcType設置為bos，則填寫百度BOS域名，如http://bj.bcebos.com 或 http://gz.bcebos.com。 如果srcType設置為ks3，則填寫金山ks3域名，如http://kss.ksyun.com或http://ks3-cn-beijing.ksyun.com或http://ks3-us-west-1.ksyun.coms。 如果srcType設置為S3， 則填寫Amazon S3各region的域名。 如果srcType設置為youpai，則填寫又拍云域名，如自動判斷最優線路http://v0.api.upyun.com或電信線路http://v1.api.upyun.com或聯通網通線路http://v2.api.upyun.com或移動鐵通線路http://v3.api.upyun.com。 如果srcType設置為cos，則填寫騰訊云bucket所在的區域，例如華南園區為ap-guangzhou。 如果srcType設置為azure，則填寫Azure Blob連接字符串中的EndpointSuffix ，如core.chinacloudapi.cn。
  srcBucket	源bucket名字或container名稱	如果srcType設置為 local、http，則不需要填寫。 如果srcType設置為azure，則填寫container名稱。 其他填寫bucket名稱。
  srcPrefix	源前綴，字符串，默認為空	如果srcType設置為local，則填寫本地目錄，需要完整路徑，以單個正斜線（/）進行分割并且以單個正斜線（/）結尾，僅支持如c:/example/ 或者/data/example/ 的格式。 重要 c:/example//或 /data//example/ 或 /data/example//是非法的。 如果srcType設置為oss、qiniu、bos、ks3、youpai、s3，則填寫待同步object的前綴，不包括bucket名稱，如data/to/oss/。 如需同步所有文件，則srcPrefix設置為空 。
  destAccessKey	目的AccessKey，字符串。	訪問OSS服務的AccessKey ID，請到阿里云控制臺查看。
  destSecretKey	目的SecretKey，字符串。	訪問OSS的AccessKey Secret，請到阿里云控制臺查看。
  destDomain	目的endpoint，字符串。	從阿里云控制臺獲取，非帶bucket前綴的二級域名，列表請參見域名列表。
  destBucket	目的bucket，字符串。	OSS的bucket名稱，不需要以/結尾。
  destPrefix	目標前綴，字符串，默認為空。	目標前綴，默認為空，直接放在目標bucket下。 如果要將數據同步到oss的某個目錄下，請以/結尾，如data/in/oss/。 注意oss不支持以/作為文件的開頭，所以destPrefix請不要配置以/作為開頭。 一個本地文件路徑為srcPrefix+relativePath的文件，遷移到oss的路徑為destDomain/destBucket/destPrefix +relativePath。 一個云端文件路徑為srcDomain/srcBucket/srcPrefix+relativePath的文件，遷移到oss的路徑為destDomain/destBucket/destPrefix+relativePath。
  srcSignatureVersion	源端簽名版本。	僅適用于云盒。 取值：oss_signature_v4，表示OSS V4簽名。
  destSignatureVersion	目的端簽名版本。	僅適用于云盒。 取值：oss_signature_v4，表示OSS V4簽名。
  srcRegion	源端地域。	僅適用于云盒。
  destRegion	目的端地域。	僅適用于云盒。
  srcCloudBoxId	源端云盒ID。	僅適用于云盒。
  destCloudBoxId	目的端云盒ID。	僅適用于云盒。
  taskObjectCountLimit	每個Task最大的文件數，整型，默認10000。	該配置項會影響到任務執行的并行度，一般配置為總文件數/Worker總數/遷移線程數（workerTaskThreadNum） ，最大值不要超過50000，如果不知道總文件數，請使用默認值。
  taskObjectSizeLimit	每個Task最大數據量，整型，單位bytes，默認1GB。	該配置項會影響到任務執行的并行度，一般配置為總數據量/Worker總數/遷移線程數（workerTaskThreadNum），如果不知道總數據量，請使用默認值。
  isSkipExistFile	數據遷移時是否跳過已經存在的文件，布爾類型。	當設置為true時，根據文件的size和LastModifiedTime判斷是否跳過；為false時，總是覆蓋OSS上已有文件。默認為值為false。
  scanThreadCount	并行掃描文件的線程數，整型。 默認值：1 有效值：1-32	該配置項與掃描文件的效率有關，沒有特殊需求請不要修改。
  maxMultiThreadScanDepth	最大允許并行掃描目錄的深度，整型。 默認值：1 有效值：1-16	默認值1表示在頂級目錄間并行掃描。 沒有特殊需求不要修改，隨意配置過大值會導致任務無法正常運行 。
  appId	騰訊云COS的appId ，整型。	srcType=cos時有效。
  httpListFilePath	HTTP列表文件的絕對路徑，字符串。	srcType=http時有效，源為HTTP鏈接地址時，需要提供內容為HTTP鏈接地址文件的絕對路徑，如c:/example/http.list。 該文件中的HTTP鏈接需要劃分成兩列，以一個或多個空格分開，分別代表前綴和上傳到OSS后的相對路徑。例如c:/example/http.list文件內容如： http://xxx.xxx.com/aa/ bb.jpg http://xxx.xxx.com/cc/ dd.jpg 指定destPrefix為ee/，則遷移到OSS的文件名如下： ee/bb.jpg ee/dd.jpg

• workers：分布式模式特有，每個IP一行。如：

  192.168.1.6
  192.168.1.7
  192.168.1.8

  • 上述配置情況下，第一行的192.168.1.6一定是 master ；即192.168.1.6上會同時啟動Master 、 Worker、TaskTracker。Console也需要在該機上運行。

  • 多個Worker機器的用戶名、登錄方式、工作目錄請確保相同。

配置文件示例

下表中是分布式部署下的數據遷移任務配置文件，單機的配置文件名是local_job.cfg，配置項與分布式部署時沒有區別。

高級設置

• 分時限流

  sys.properties中的workerMaxThroughput(KB/s)表示Worker流量的上限，如果業務需要限流，例如源端流控控制、網絡限制等情況。該參數的值應該小于機器的最大網絡流量，并根據業務需要評估。修改后需要重啟服務才能生效。

  分布式部署情況下，需要修改每個Worker的$OSS_IMPORT_WORK_DIR/conf下的sys.properties，然后重啟服務。

  要實現分時限流，可通過crontab定時修改sys.properties，然后重啟服務生效。

• 修改任務并發數

  • sys.properties中的workerTaskThreadNum表示Worker并發執行的任務數量，如果網絡較差、并發大，會出現大量超時錯誤，此時應該修改此配置，降低并發量，并重啟服務。

  • sys.properties中的workerMaxThroughput(KB/s)表示Worker流量的上限，如果業務需要限流，例如源端流控控制、網絡限制等情況。該參數的值應該小于機器的最大網絡流量，并根據業務需要評估。

  • job.cfg中的taskObjectCountLimit ，每個Task 最大的文件數，默認10000。該參數會影響Task的數量，數量過小無法實現有效的并發。

  • job.cfg中的taskObjectSizeLimit ， 每個Task最大數據量，默認1GB。該參數會影響Task的數量，數量過小無法實現有效的并發。

    重要

    • 請在啟動遷移任務前，完成各項參數配置。

    • sys.properties中的參數修改后，重啟遷移服務器后才能生效。

    • job.cfg任務提交后，任務的配置參數無法更改。

• 只校驗不遷移數據

  ossimport支持只校驗數據不遷移數據，設置任務配置文件job.cfg或local_job.cfg的配置項jobType為audit而不是import，其他配置與數據遷移相同。

• 數據遷移增量模式

  數據遷移增量模式，是指數據遷移任務啟動后，先進行一次全量遷移，每隔一段時間自動的進行增量數據遷移。第一次數據遷移任務為全量遷移，提交任務后立即啟動；后面的增量數據遷移每隔一個周期啟動一次。數據遷移增量模式適用于數據備份和數據同步。

  增量模式有兩個配置項：

  • job.cfg中的isIncremental ，表示是否打開增量遷移模式， true表示打開增量模式，false表示關閉增量模式，默認關閉。

  • job.cfg中的incrementalModeInterval，表示增量模式下的同步間隔，即增量數據遷移的間隔周期，單位秒。isIncremental=true時有效?？膳渲玫淖钚≈禐?span data-tag="ph" id="codeph-0e6-9ql-kih" class="ph">900秒 ，不建議配置成小于3600秒的值，會浪費大量請求，造成額外的系統開銷。

• 指定遷移文件的過濾條件

  遷移文件的過濾條件，即只遷移滿足特定條件的文件。ossimport支持指定前綴和最后修改時間：

  • job.cfg中的srcPrefix，用來指定遷移文件的前綴，默認為空。

    • 如果srcType=local，則填寫本地目錄。填寫時需要完整路徑，以正斜線（/）進行分割并且以正斜線（/）結尾，如c:/example/或/data/example/。

    • 如果srcType為oss、qiniu、bos、ks3、youpai、s3，則為待同步object的前綴，不包括bucket名稱。如data/to/oss/。遷移所有文件時srcPrefix設置為空。

  • job.cfg中的importSince，用來指定遷移文件的最后修改時間，單位秒。importSince為Unix時間戳，即自1970年1月1日UTC零點以來的秒數，通過命令date +%s獲取。默認值0，表示遷移全部數據。增量模式下只對第一次全量遷移有效，非增量模式對整個遷移任務有效。

    • 如果文件的LastModified Time在importSince之前，文件不被遷移。

    • 如果文件的LastModified Time在importSince之后，文件將被遷移。