Поделиться через


Безопасная отладка исходного кода путем публикации исходных карт на сервере символов Azure Artifacts

Чтобы безопасно просматривать исходный код разработки и работать с ним в Средствах разработки, а не скомпилированный, минималифицированный и объединенный рабочий код, возвращаемый веб-сервером, используйте исходные карты, обслуживаемые сервером символов Azure Artifacts.

Публикация исходных карт непосредственно на веб-сервере сделает исходный исходный код общедоступным. Чтобы не сделать исходный исходный код общедоступным, опубликуйте исходные карты на сервере символов Azure Artifacts. Такой подход позволяет использовать исходные карты в средствах разработки при отладке рабочего веб-сайта без публикации исходных карт на веб-сервере.

Исходные карты сопоставляют скомпилированный рабочий код с исходными файлами разработки. Затем в средствах разработки можно просматривать и работать с привычными исходными файлами разработки, а не скомпилированным кодом. Дополнительные сведения о сопоставлении исходного кода и использовании карт источников в средствах разработки см. в статье Сопоставление обработанного кода с исходным исходным кодом для отладки.

Концепции

Необходимо индексировать исходные карты на сервере символов Azure Artifacts, чтобы исходные карты были доступны в Средствах разработки при отладке рабочего веб-сайта.

Для этого добавьте строковое x_microsoft_symbol_client_key свойство в исходные карты во время компиляции. Это свойство содержит шестнадцатеричное значение в нижнем регистре 256-разрядного хэша SHA-2 соответствующего исходного файла.

После этого DevTools сможет вычислить этот хэш для каждого скомпилированного файла и использовать хэш, чтобы получить правильную исходную карту с сервера символов Azure Artifacts. Чтобы безопасно получить исходные карты, DevTools использует предоставленный вами личный маркер доступа для подключения к серверу символов Azure Artifacts.

Шаг 1. Создание личного маркера доступа для Azure DevOps

Для публикации исходных карт с сервером символов Azure Artifacts требуется личный маркер доступа (или PAT). Этот PAT будет использоваться системой сборки при компиляции кода и публикации карт источников.

Чтобы создать PAT в Azure DevOps, выполните приведенные далее действия.

  1. Войдите в свою организацию Azure DevOps, перейдя по адресу https://dev.azure.com/{yourorganization}.

  2. В Azure DevOps перейдите в раздел Параметры пользователей.Личные маркеры> доступа:

    Меню

    Откроется страница Личные маркеры доступа :

    Страница

  3. Щелкните Создать токен. Откроется диалоговое окно Создание личного маркера доступа :

    Диалоговое окно

  4. В текстовом поле Имя введите имя pat, например "опубликовать карты источника".

  5. В разделе Срок действия введите дату окончания срока действия для PAT.

  6. В разделе Области щелкните Показать все области , чтобы развернуть раздел.

  7. Прокрутите вниз до раздела Символы и установите флажок Чтение & записи .

  8. Нажмите кнопку Создать. Откроется диалоговое окно Успешно:

    Диалоговое окно

  9. Нажмите кнопку Копировать в буфер обмена , чтобы скопировать PAT. Обязательно скопируйте маркер и сохраните его в безопасном расположении. Для вашей безопасности он не будет отображаться снова.

Дополнительные сведения о PAT см. в статье Использование личных маркеров доступа.

Шаг 2. Вычисление хэша SHA-256 скрипта и добавление его в исходные карты

На последнем этапе процесса сборки приложения для каждой исходной карты, которую требуется опубликовать, необходимо вычислить хэш SHA-256 файла JavaScript, которому соответствует исходная карта, и добавить его в карту источника с помощью x_microsoft_symbol_client_key свойства string.

Системы сборки зависят от приложения к приложению, поэтому нет четкого единого способа применения этого приложения. Но вот пример подключаемого модуля Webpack 5, который можно добавить в конфигурацию Webpack, если вы используете его:

// file: webpack.plugin-symbols.js
// Copyright (C) Microsoft Corporation. All rights reserved.
// Licensed under the BSD 3-clause license.

const crypto = require('crypto');

module.exports = class PrepareSourceMapsForSymbolServerPlugin {
  /**
   * @param {import('webpack').Compiler} compiler
   * @returns {void}
   */
  apply(compiler) {
    compiler.hooks.emit.tap('PrepareSourceMapsForSymbolServerPlugin', (compilation) => {
      const files = Object.keys(compilation.assets);
      const sourceMaps = files.filter(v => v.endsWith('.map'));
      const sourceFilesAndMapsNames = sourceMaps.map(mapFileName => {
        const sourceFileName = mapFileName.substring(0, mapFileName.length - 4);
        return {
          sourceFileName,
          mapFileName,
        };
      });
      const sourceFiles = sourceFilesAndMapsNames.map(({ sourceFileName, mapFileName }) => {
        const sourceFile = compilation.assets[sourceFileName];
        const sourceFileBuffer = sourceFile.buffer();
        const hasher = crypto.createHash('sha256');
        hasher.write(sourceFileBuffer);
        const digest = hasher.digest();
        const sourceFileHash = digest.toString('hex');

        const sourceMapAsset = compilation.assets[mapFileName];
        const sourceMapSource = sourceMapAsset.source();
        const sourceMapContents = JSON.parse(sourceMapSource);
        sourceMapContents['x_microsoft_symbol_client_key'] = sourceFileHash;
        const rewrittenSourceMapContents = JSON.stringify(sourceMapContents);
        if (!sourceMapAsset.isBuffer()) {
          // Not a buffer -- write to the _value property
          sourceMapAsset._value = rewrittenSourceMapContents;
        } else {
          sourceMapAsset._valueAsBuffer = Buffer.from(rewrittenSourceMapContents, 'utf-8');
        }

        return {
          sourceFileName,
          mapFileName,
          sourceFileHash,
          sourceMapAsset,
        };
      });
    });
  }
};

Затем вы можете добавить подключаемый модуль plugins в раздел в webpack.config.js файле конфигурации:

const PrepareSourceMapsForSymbolServerPlugin = require('./webpack.plugin-symbols.js');

// ...

module.exports = (env, args) => {
  const mode = process.env.NODE_ENV || (env && env.NODE_ENV) || 'production';
  return {
    devtool: mode === 'production' ? 'hidden-source-map' : 'inline-source-map',
    resolve: {
      modules: [
        path.resolve('./node_modules'),
      ],
    },
    output: {
      publicPath: '/',
      filename: '[name].bundle.js',
      chunkFilename: '[name].chunk.js',
    },
    plugins: [
        // ... other plugins
        new PrepareSourceMapsForSymbolServerPlugin(),
    ]
  };
};

Шаг 3. Публикация исходных карт на сервере символов Azure Artifacts

Чтобы опубликовать исходные карты на сервере символов Azure Artifacts, используйте один из следующих подходов:

Эти подходы описаны ниже.

Публикация исходных карт с помощью Azure DevOps Pipelines

Azure DevOps поставляется с задачей сборки PublishSymbols@2 конвейера. Эту задачу можно использовать для публикации исходных карт на сервере символов Azure Artifacts.

При настройке этой задачи задайте для indexableFileFormats параметра значение All или SourceMap.

Публикация исходных карт с помощью symbol.exe

Команда сервера символов публикует приложение .NET Core, symbol.exeкоторое можно скачать автоматически. Для программной загрузки symbol.exeиспользуйте GET метод конечной Client точки в REST API службы символов, как описано в разделе Клиент — получение. Затем выполните следующую команду, чтобы опубликовать исходные карты на сервере символов Azure Artifacts:

symbol publish
        -d {root directory containing your source maps}
        -n {a unique name for this job}
        -s {service URL, such as https://artifacts.dev.azure.com/contoso}
        --patAuthEnvVar {name of environment variable containing a PAT}
        --indexableFileFormats SourceMap

Параметр -n должен быть уникальным. Повторяющиеся имена заданий будут отклонены, включая имена заданий, которые завершили сбой.

См. также