.. highlight:: console

=============================
 在 CI/CD 管线中使用 Pyarmor
=============================

:ref:`直接使用方式` 基本不改变原来 CI/CD 的管线流程，适用于

- 试用版
- :term:`Pyarmor 基础版`
- :term:`Pyarmor 管线版`

:ref:`间接使用方式` 需要改变原来的 CI/CD 管线流程，任何许可证都可以使用

直接使用方式
============

**试用版** 可以直接在 CI/CD 管线中使用，只需要增加一个步骤::

      pip install pyarmor

:term:`Pyarmor 基础版` 和 :term:`Pyarmor 管线版` 许可证

- 首先完成 :ref:`initial registration` ，得到许可证 :term:`注册文件` ``pyarmor-regfile-xxxx.zip``
- 其次在本地联网设备上申请 :term:`管线注册文件`::

      $ pyarmor reg -C pyarmor-regfile-xxxx.zip

  申请一次即可，该命令执行成功之后会在当前目录创建 :term:`管线注册文件` ``pyarmor-ci-xxxx.zip``

  在本地设备上面查看管线许可证的相关信息::

      $ pyarmor --home temp reg pyarmor-ci-xxxx.zip

- 在管线中增加如下命令::

      # 请替换 9.X.Y 为当前 Pyarmor 的版本
      pip install pyarmor==9.X.Y
      parmor reg pyarmor-ci-xxxx.zip

  在管线中查看注册信息::

      pyarmor -v

注意事项

- 管线注册文件有效期为一年，可以用于在 CI/CD 中注册 Pyarmor
- 管线注册文件在当前 Pyarmor 的版本有效，但是不一定在升级之后的 Pyarmor 中有效
- 每一个许可证最多可以申请 100 个管线注册文件，超过申请次数之后就无法在申请
- 请勿在 CI/CD 管线中申请管线注册文件，因为请求次数有一定限制

.. important::

   每次管线运行命令 `pyarmor gen` 都会向 Pyarmor 许可证发送验证请求，过多的请求或者超过正常使用的请求可能会被拒绝，目前的限制是

   - 每秒至多 1 次注册
   - 每小时至多 100 次注册
   - 每天至多 1,000 次注册
   - 每月至多 10,000 次注册

   超过此限制的用户请查看下面的高频次使用的解决方案

.. important::

   只允许在开发设备上安装和注册 Pyarmor，不允许在需要发送给客户的 Docker 镜像中安装和注册 Pyarmor

.. note::

   在 GitHub Action 中需要额外的一个操作步骤，否则会报错 `CI license only works in CI/CD pipeline`

   1. 对于 ubuntu ，增加操作步骤::

        - run: sudo mv /dev/disk /dev/disk-none

   2. 对于 darwin ，增加操作步骤::

        - run: sudo mv /dev/rdisk0 /dev/rdisk0-none

   请参考这里 `Error when using CI license in CI pipeline <https://github.com/dashingsoft/pyarmor/discussions/2004>`_

管线注册文件的有效期
--------------------

一般情况下，下列情况需要重新申请更新

- 在管线版许可证到期之后，此前申请的管线文件都会失效。在续费成功之后，需要重新申请新的管线注册文件。
- 使用低版本的 Pyarmor 申请的管线注册文件，可能无法在高版本的 Pyarmor中使用，一般情况下需要在升级 Pyarmor 之后，在最新的版本中重新申请管线注册文件。升级补丁版本不需要重新申请，例如从 9.1.3 升级到 9.1.8 无需重新申请，但是从 9.1.8 升级到 9.2.0 就需要重新申请
- Pyarmor 开发组检测到某个许可证出现非正常的使用，会停用该许可证。如果核实为正常使用之后，需要重新申请新的管线注册文件

高频次使用的解决方案
--------------------

.. versionadded:: 9.2.0

如果一次构建使用了多个 `pyarmor gen` 命令，可以合并多个命令到一个，例如::

    # 原来使用三个 pyarmor gen
    pyarmor gen -R /path/to/package1
    pyarmor gen -R /path/to/package2
    pyarmor gen -R /path/to/package3

    # 可以合并成为一个
    pyarmor gen -R /path/to/package1 /path/to/package2 /path/to/package2

或者使用一个 Python 脚本，在同一个进程当中执行所有的 `pyarmor gen`

例如，创建一个脚本 `batch.py`:

.. code-block:: python

    import os
    import shlex

    from pyarmor.cli.__main__ import main_entry as pyarmor_run

    # 不要在脚本中运行 `pyarmor reg pyarmor-ci-xxxx.zip`

    # 使用下面的方式等价运行命令 pyarmor gen -R /path/to/package1
    pyarmor_run(['gen', '-R', '/path/to/package1'])

    # 或者这种形式，更接近原来的命令
    cmdlist = shlex.split("pyarmor gen -R /path/to/package2")
    pyarmor_run(cmdlist[1:])

    # 切换当前路径
    os.chdir('/path/to/other')

    # 执行其它命令
    cmdlist = shlex.split("pyarmor gen key -e 30")
    pyarmor_run(cmdlist[1:])

然后在工作流中使用下面的方法调用::

    $ pyarmor reg pyarmor-ci-8000.zip
    $ python3 batch.py

如果上述方案还是无法解决，那么需要使用专门的许可证服务器进行验证。

Pyarmor 开发组需要核实项目的真实性，以及使用的合理性，然后会重置许可证的验证方式，用户需要重新申请管线注册文件。

每一个月的免费限额是 1 万次，如果超过限额，需要根据项目平均使用量额外收费:

- 每月限额在 10 万次，每年额外支付 50 元
- 每月限额在 20 万次，每年额外支付 100 元
- 每月限额在 30 万次，每年额外支付 150 元
- ...

间接使用方式
============

因为加密后的脚本等价于原来的脚本外加运行辅助包，所以可以首先在本地设备对脚本进行加密，然后把加密后的脚本保存到一个单独的分支，CI/CD 管线流程直接从加密分支中获取数据，这种方式适用于任何许可证

下面我们用一个示例来进行简单说明

假设我们的测试项目位于 `https://github.com/dashingsoft/test-project` ，其目录结构如下::

    $ tree test-project

    test-project
    └── src
        ├── main.py
        ├── utils.py
        └── parent
            ├── child
            │   └── __init__.py
            └── __init__.py

可以首先在本地加密脚本，并保存到分支 `master-obf` ，下面是示例脚本:

.. code-block:: bash

    $ git clone https://github.com/dashingsoft/test-project

    $ pip install pyarmor
    $ pyarmor reg /path/to/pyarmor-regfile-5068.zip

    # 创建新分支
    $ git checkout -B master-obf

    # 创建输出目录 dist ，链接到项目目录
    $ ln -s test-project dist

    # 加密所有的脚本到输出目录 "dist" ，因为它等同于 "test-project"
    # 所以加密后的脚本 "dist/src/main.py" 会覆盖原来的脚本 "test-project/src/main.py"
    $ pyarmor gen -O dist -r --platform windows.x86_64,linux.x86_64,darwin.x86_64 test_project/src

    # 增加运行辅助包到这个分支
    $ git add -f test_project/pyarmor_runtime_5068/*

    # 提交加密结果和运行辅助包
    $ git commit -m'Build obfuscated scripts' .

    # 创建远程分支
    $ git push -u origin master-obf

对于 CI/CD 管线来说，只需要使用分支 `master-obf` 就基本可以和以前的方式一样不受限制的运行

.. include:: ../_common_definitions.txt