Эррата — это вкладка с опечатками, которую вкладывают в книгу. Оба исправления 3.6.3 нашлись одинаково: открываешь страницу, которая работала, и получаешь 404. Первое — срез пути, из-за которого имя файла теряло первую букву. Второе — конфиг, который при неудачном чтении заменялся умолчаниями. Основной разбор платформы — в статье MD Viewer: просмотрщик Markdown без браузерного движка; здесь про MD.Scribe 3.6.3, механику обеих ошибок и что проверено на живом прогоне.

md scribe 3 6 3 cover

TL;DR: две ошибки, один симптом

  1. Имена без первой буквы. index.md отображался как ndex.md, и каждая ссылка из браузера вела в 404.
  2. Причина — симлинк. Обход шёл по разрешённому пути, а срез считался от неразрешённого; префиксы разной длины.
  3. Конфиг не перезаписывается. Нечитаемый файл настроек теперь даёт работу на умолчаниях и строку в логе, а не потерю 1 166 байт.
  4. Проверка. Прогон на раскладке релиза: имена полные, ?file=docs/upgrade-from-v2.md отвечает 200.
  5. Архив: 4 272 892 байта, 1 023 записи, манифест 3.6.3.

Что нового

Область Изменение
Пути относительный путь считается от разрешённого корня
Вне корня путь логируется и пропускается, а не обрезается
Тесты три теста на раскладку с симлинком
Конфиг различаются «распарсено», «пусто» и «есть, но не читается»
Запись конфига при нечитаемом файле запрещена, событие в журнале
Тесты конфига два, на Windows пропускаются

Ключевые изменения

Срез пути и потерянная буква

flowchart TB
  ROOT["корень обзора: разрешённый realpath"] --> WALK["обход файлов"]
  WALK --> FULL["полный путь файла"]
  FULL --> CUT["срез префикса"]
  CUT --> REL["относительный путь в ссылке"]
  REL --> VIEW["просмотр ?file=..."]

Механика такая. Проверка пути возвращает каталог, уже развёрнутый через realpath(). Обход идёт по этой базе. А относительный путь строился как substr($full, strlen($root)), где $root — неразрешённый корень обзора.

Пока content — обычный каталог, оба префикса совпадают, и всё работает. Но в раскладке релиза content это симлинк: <release>/content -> mdscribe-data/content. Длины префиксов расходятся, срез попадает внутрь последнего сегмента, и каждый файл в подкаталоге теряет первую букву.

На боевом сайте это выглядело так: index.md показывался как ndex.md, а autoyap-roles-security-2026-11-13.md — как utoyap-roles-security-2026-11-13.md. При этом сам просмотрщик был исправен: прямой запрос с правильным путём отдавал 200. То есть сломана была не отрисовка, а генерация ссылок.

Теперь путь считается от того же разрешённого корня, с которого начался обход, а путь вне корня логируется и пропускается вместо обрезки. Три теста строят раскладку с симлинком; со старой арифметикой все три падают.

Конфиг, который нельзя прочитать

flowchart TD
  L["загрузка настроек"] --> R{"файл читается?"}
  R -- да --> USE["работа с настройками"]
  R -- нет --> SAFE["умолчания, запись запрещена"]
  SAFE --> LOG["строка в журнале ошибок"]

Вторая ошибка опаснее первой, потому что тихая. Config::load() считал «файл есть» равнозначным «файл читается», продолжал работу с пустыми значениями и вызывал appendMissingKeys() — а тот перезаписывал файл.

В проде это выглядело так: конфиг, записанный из CLI от root с правами root:root 0640, не читался пулом веб-сервера. Следующий запрос заменил 1 166 байт настроек умолчаниями — вместе с именем сайта и домашним документом, и без единой строки в логе.

Теперь чтение различает три состояния: ключи распарсены; файл пуст или отсутствует (законный первый запуск); файл есть, но не читается. В третьем случае приложение работает на умолчаниях, писать конфиг запрещено, а в журнал ошибок попадает запись.

Установка и обновление

unzip MD.Scribe-3.6.3.zip -d /srv/releases/3.6.3
chmod -R u+w /srv/releases/3.6.3/storage
ln -sfn /srv/releases/3.6.3 /srv/docs      # docroot: /srv/docs/public
Шаг Что сделать
1 сохранить каталог данных (mdscribe-data или ваш)
2 распаковать архив в новый каталог релиза
3 убедиться, что content — симлинк на данные, а не копия
4 переключить симлинк docroot
5 сбросить opcache
6 открыть список файлов и проверить имена

Проверка после обновления

flowchart LR
  SYM["content — симлинк"] --> MIS["префиксы разной длины"]
  MIS --> TRUNC["имя без первой буквы"]
  TRUNC --> E404["ссылка ведёт в 404"]
  E404 --> FIX["срез от того же корня"]
  FIX --> OK["полные имена и 200"]
Проверка Ожидаемо
Список файлов полные имена, без потери первой буквы
Файл в подкаталоге ссылка вида ?file=docs/upgrade-from-v2.md отвечает 200
Имя сайта прежнее, не «MD.Scribe» по умолчанию
Домашний документ прежний, а не index.md из умолчаний
Журнал ошибок нет записей о нечитаемом конфиге
Права на конфиг владелец — пользователь пула, не root

Замеры и цифры

Проверено 15.11.2026, двумя проверками.

Что Значение
Архив MD.Scribe-3.6.3.zip 4 272 892 байта, SHA-256 80da2cc0…7dc1852
Записей в архиве 1 023, отсортированы
Режимы файлов все 420 (0o644)
Манифест MD.Scribe 3.6.3, php_min 8.5.0, 988 файлов
Прогон: раскладка релиза с симлинком content собрана, сервер PHP 8.5.4
Главная страница 200
Ссылки в разметке file=index.md, file=getting-started.md, file=docs/api.md — полные, без обрезки
?file=index.md 200
?file=getting-started.md 200
?file=docs/markdown-reference.md 200
?file=docs/upgrade-from-v2.md 200
MD.Scribe 3.6.3: архив и прогон на раскладке с симлинком

Прогон специально воспроизводил ту самую раскладку: каталог content вынесен в данные и подключён симлинком. Именно в ней старая арифметика ломалась. Результат — имена в разметке полные, а файл из подкаталога открывается по прямой ссылке; раньше такой запрос давал 404, потому что имя приходило без первой буквы и без папки.

Заодно проверка показала, что в демо-контенте намеренно есть ссылка на отсутствующий файл (definitely-missing.md) — это иллюстрация страницы 404, а не дефект.

Совместимость

Параметр 3.6.2 3.6.3
Минимум PHP 8.5.0 8.5.0
Файлов в манифесте 988 988
Архив 4 267 955 байт 4 272 892 байта
Записей в архиве 1 022 1 023

Минимум PHP не менялся. Условия, при которых ошибка проявлялась, — симлинк на каталоге контента и права конфига, отличающиеся от пользователя пула.

Кто обновляется Что учесть
с 3.6.0–3.6.2 проверьте имя сайта и домашний документ: они могли сброситься на умолчания
с 3.5.0 то же плюс проверка симлинка content
с 3.1.0 нужен PHP 8.5

Подводные камни

  • Проверяйте владельца конфига. Файл, записанный от root, пул не прочитает; до 3.6.3 это приводило к перезаписи умолчаниями.
  • Запись конфига — от пользователя пула. Из CLI это значит запуск через su/sudo -u, а не от root.
  • Симлинк content — часть раскладки. Если заменить его копией, ошибка не воспроизведётся, но и обновления будут терять контент.
  • Имена без первой буквы — признак среза пути. Если увидели ndex.md, дело не в шаблоне.
  • 404 при работающем просмотрщике. Проверяйте прямой запрос с полным путём: если он даёт 200, ломается генерация ссылок.
  • Пустой конфиг — законный случай. Первый запуск отличается от нечитаемого файла; не путайте при диагностике.
  • Логи теперь говорят. После 3.6.3 событие «конфиг не читается» попадает в журнал ошибок — ищите там.
  • Кэш браузера. После переключения релиза старые ссылки могут остаться в кэше.
  • opcache. Без сброса увидите старую версию кода и решите, что исправление не помогло.
  • Демо-ссылка на отсутствующий файл. Не считайте её регрессией.

FAQ

Почему имена теряли первую букву?

Обход шёл по разрешённому пути, а префикс для среза брался от неразрешённого. При симлинке длины различались, и срез съедал первый символ.

Почему просмотрщик при этом работал?

Потому что ломалась генерация ссылок, а не разрешение пути: прямой запрос с корректным путём отдавал 200.

Что было с конфигом?

Нечитаемый файл считался пустым, и приложение перезаписывало его умолчаниями, теряя настройки без записи в лог.

Как проверить, что меня это коснулось?

Сравните имя сайта и домашний документ с ожидаемыми: если там значения по умолчанию, настройки были сброшены.

Как писать конфиг, чтобы не повторить?

От имени пользователя пула: файл с владельцем root пул не прочитает.

Нужен ли PHP 8.5?

Да, минимум не менялся с 3.5.0.

Итог

MD.Scribe 3.6.3 — релиз про две ошибки, которые не выглядели ошибками: имена файлов без первой буквы и конфиг, который «сам сбрасывался». Обе нашлись с одной стороны — со стороны пользователя, упёршегося в 404 и в пропавшие настройки. Исправления точечные: путь считается от того же разрешённого корня, а нечитаемый конфиг больше не перезаписывается. Прогон на раскладке с симлинком подтверждает: имена полные, файл из подкаталога открывается, манифест показывает 3.6.3 с 988 файлами.

Цитата: Самая дорогая ошибка — та, что выглядит как особенность: имя без буквы и настройки «сами сбросились».

Связанные материалы

LLM Summary

  • Тема: MD.Scribe 3.6.3 «Errata» — исправление среза пути в списке файлов и защита конфига от перезаписи умолчаниями.
  • Дефект 1: scan() строил относительный путь как substr($full, strlen($root)), где $full — путь от базы, развёрнутой realpath(), а $root — неразрешённый корень обзора; при симлинке content -> mdscribe-data/content префиксы разной длины и первый символ имени терялся. В проде: index.md → ndex.md, autoyap-roles-security-2026-11-13.md → utoyap-roles-security-2026-11-13.md, все ссылки из браузера давали 404 при исправном просмотрщике.
  • Исправление 1: путь считается от того же разрешённого корня, путь вне корня логируется и пропускается; три теста на раскладку с симлинком, со старой арифметикой падают все три.
  • Дефект 2: Config::load() считал «файл есть» равным «файл читается» и вызывал appendMissingKeys(), перезаписывая настройки умолчаниями; в проде конфиг root:root 0640 не читался пулом, и 1 166 байт настроек (имя сайта, домашний документ) были потеряны без записи в лог.
  • Исправление 2: различаются распарсенные ключи, пустой/отсутствующий файл и существующий нечитаемый; в последнем случае работа на умолчаниях, запись запрещена, событие в журнале; два теста (на Windows пропускаются).
  • Проверено 15.11.2026: архив — 4 272 892 байта, SHA-256 80da2cc0532471efb5110be241077330501ba0c0f9811748b294264ab7dc1852, 1 023 записи, отсортированы, режимы 420, манифест 3.6.3 / 988 файлов / php_min 8.5.0.
  • Прогон на раскладке релиза (PHP 8.5.4, content — симлинк на данные): главная 200, ссылки в разметке полные; ?file=index.md, ?file=getting-started.md, ?file=docs/markdown-reference.md, ?file=docs/upgrade-from-v2.md — все 200.
  • Грабли: конфиг писать от пользователя пула; симлинк content не заменять копией; сбрасывать opcache; демо-ссылка definitely-missing.md — намеренная.
  • Не проверялось: воспроизведение исходного дефекта на коде 3.6.2, работа под нагрузкой, поведение при обновлении DSM-подобных раскладок с несколькими симлинками.
  • Ссылки: https://github.com/paulmann/MD.Scribe, https://sysadministrator.ru/md-viewer/

Промт для агента (установка и настройка)

Готовый промт: скопируйте блок целиком. Источник шагов — AGENTS.md и README.md репозитория, сверено с прогоном на раскладке релиза 15.11.2026.

Задача: обновить MD.Scribe до 3.6.3 и убедиться, что список файлов отдаёт полные имена, а настройки не сброшены.

Материалы:
- репозиторий: https://github.com/paulmann/MD.Scribe
- AGENTS.md: https://github.com/paulmann/MD.Scribe/blob/main/AGENTS.md
- README: https://github.com/paulmann/MD.Scribe/blob/main/README.md
- релиз: https://github.com/paulmann/MD.Scribe/releases/tag/v3.6.3

Шаг 1. Сверить SHA-256 архива с указанным в релизе.
Шаг 2. Проверить PHP 8.5 и расширения mbstring, dom, libxml, json, zip.
Шаг 3. Сохранить каталог данных и конфиг .md.ini.
Шаг 4. Распаковать архив в новый каталог релиза, content оставить симлинком на данные.
Шаг 5. Проверить владельца .md.ini: он должен быть пользователем пула, а не root.
Шаг 6. Переключить симлинк docroot и сбросить opcache.
Шаг 7. Открыть список файлов: имена должны быть полными, без потери первой буквы.
Шаг 8. Открыть файл из подкаталога по прямой ссылке ?file=docs/<имя>.md — ожидается 200.
Шаг 9. Сверить имя сайта и домашний документ с ожидаемыми значениями.
Шаг 10. Проверить журнал ошибок: не должно быть записей о нечитаемом конфиге.
Шаг 11. Записать конфиг из CLI только от имени пользователя пула: su -s /bin/sh <pool-user> -c "php ..."

Запрещено:
- писать конфиг от root: пул его не прочитает;
- заменять симлинк content копией каталога;
- проверять после обновления с прогретым opcache;
- считать ссылку на отсутствующий файл регрессией: в демо-контенте она намеренная;
- откатываться на 3.6.2 «если что»: там теряется конфиг при нечитаемом файле;
- игнорировать записи о нечитаемом конфиге в журнале.

Что считать успехом: имена в списке полные, файл из подкаталога открывается по прямой ссылке, настройки на месте, в журнале ошибок нет записей о конфиге, манифест показывает 3.6.3.