Описание программы formCrawler (c) Botmaster Labs


1. Краткое описание:

На сайтах, заданных в текстовом файле
<папка_сайта>/formcrawler/src/LinksList id1.txt
(формат файла - текстовый список доменов или ссылок)
formCrawler ищет формы, исключая поисковые,
и складывает результат в текстовый файл
<папка_сайта>/formcrawler/res/FormsFound.txt
в формате:
исходная_ссылка_или_домен - ссылка_с_найденной_формой
Если не найдено - складывает в файл
<папка_сайта>/formcrawler/res/FormsNotFound.txt
в формате:
исходная_ссылка_или_домен - текст_ошибки

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

Порядок работы: админ через админку запускает демон и
управляет им. Демон в свою очередь, обрабатывает
страницы сайтов, сохраняет результаты и общается с админкой.

2. Установка:

	2.1. Требования к железу сервера

1) Интернет-канал от 1 Мбит/с.
2) Объём оперативной памяти от 1 ГБ.
3) Объём дискового пространства от 10 ГБ.

	2.2. Требования к ПО сервера
	
Apache, например, 2.4
Хорошо, если Apache будет настроен применять директивы,
заданные в файлах .htaccess - это лучше обезопасит
от доступа к Вашим результатам извне.

PHP 5.3 обязательно с поддержкой libevent, sockets.
Должно быть разрешено выполнение функций PHP:
exec() - для Linux, popen(),pclose() - для Windows
Это нужно для запуска демона из админки,
иначе его придётся запускать вручную из командной строки.
Должны быть разрешены короткие тэги (short_open_tag = On).
Скриптам должно быть выделено 1 ГБ памяти.

Файрволл должен пропускать tcp-соединения, устанавливаемые PHP с сайтами.

Примечание для Windows.
В Windows по умолчанию число одновременно открываемых соединений ограничено 10.
Если не устраивает, надо поискать решение в интернете по словам
"half-open limit fix".
На сегодня (2012-05-10) для Windows можно взять
 - Apache 2.4.2 отсюда http://www.apachelounge.com/download/
 - PHP 5.3.13 отсюда http://windows.php.net/download/#php-5.3-ts-VC9-x86
 - php_libevent.dll отсюда
http://vladimirbarbarosh.blogspot.com/2011/05/compile-php-536-pecl-libevent-004.html
	  
	2.3. Установка
	
Разархивируйте файлы в корень сайта.
В Linux на все создавшиеся папки назначьте всем права на чтение и запись - 0666.
на все файлы - тоже 0666.

	2.4. Настройка запуска из командной строки в Linux (в Windows не обязательно)

Найдите папку с запускаемыми файлами, используя команду whereis,
например,
whereis php
или
whereis bash
Создайте в папке с запускаемыми файлами файл formcrawler
с нижеследующим содержимым, только
с Вашими путями до bash, корня сайта и php.
------------ Начало файла:
#!/bin/bash
cd <папка_сайта>
/usr/bin/php -f formcrawler_daemon.php
------------ Конец файла.
Проставьте на файл права 0777.
Админка будет использовать его для запуска демона.
После этого, набирая в командной строке formcrawler,
сможете его запускать консольно. Проверьте, запускается ли консольно.

	2.5. Настройка доступа в админку
	
Укажите доступ в админку.
Для этого в файле
<папка_сайта>/formcrawler/admin_ips.txt
пропишите IP, с которых можно заходить в админку,
каждый IP на своей строке. Диапазоны задаются недоуказанием полного IP.
Например, если необходим доступ с локальных айпи 127.*.*.* и 192.168.*.*
следует написать:
127.
192.168.
В случае диапазонов точка в конце обязательна.
После символа # текст считается комментарием, пустые строки разрешены.

	2.6. Указание параметров демона

В конфиге	
<папка_сайта>/formcrawler/server_cfg.php
нужно, соблюдая синтаксис языка PHP и кодировку UTF-8 без BOM,
указать параметры демона, используя справку внутри этого файла.
Для правки рекомендуется использовать редактор с подсветкой
синтаксиса, например, Notepad++
http://notepad-plus-plus.org/

	2.7. Задание списка сайтов для поиска формы.
	
Положите файл с заданиями в папку сайта
<папка_сайта>/formcrawler/src/LinksList id1.txt
В Linux установите права для чтения - 0644.
	
	2.8. Установка завершена.


3. Использование.

	3.1 Откройте в браузере админку.
Зайдите по адресу:	
http://<ваш_сайт>/formcrawler.php
Админская часть доступна тем IP, которые прописаны в файле
<папка_сайта>/formcrawler/admin_ips.txt
(см. пункт 2.3.) Остальные видят ошибку 404 Not Found
Админку желательно открывать в браузерах Firefox, Chrome, Opera.

	3.2. Через некоторое время отобразится текущее состояние демона.
Если не запущен, то "can start".
Если запущен, то будет указан его IP и порт.

	3.2. Прочитайте блок help внизу админки, нажав на кнопку [+],
чтобы познакомиться с сокращениями интерфейса, которые позже
позволят быстрее воспринимать часто меняющуюся информацию.
	
	3.3. В блоке "threads control" установите необходимое количество
одновременно обрабатываемых сайтов (далее для краткости "число потоков",
что не точно в терминах программирования). Для начала можно указать 10.

	3.4. В блоке "deamon control" нажмите кнопку [start].
Через некоторое время демон должен запуститься и начать выполнять задания,
постепенно выходя на заданое число потоков.

	3.5. Выбор оптимального числа потоков.
Если у Вас быстрый канал до вашего сайта с formCrawler,
то Вы можете легко подобрать оптимальное число потоков.
Т.е. максимальное число для конкретного сервера, такое,
что на все потоки хватает и интернет-канала, и памяти, и процессора.
1) Для подбора постепенно увеличивайте число потоков во время обработки сайтов.
Когда прорисовка состояний потоков в современных браузерах Firefox, Chrome, Opera
будет происходить с задержкой около 15-30 секунд, значит достигнут максимум потоков.
2) Установите число потоков, равное 80% от этого числа потоков.
Через некоторое время число потоков снизится
и прорисовка должна стать снова быстрой.

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

	3.7. Для плавной остановки демона установите 0 потоков.
Демон дообработает сайты. После того как список потоков станет пустым,
демон можно останавливать кнопкой [stop]. Для срочной остановки сразу
нажимайте [stop]. После этого задания будут выполняться заново.

	3.8. В процессе обработки общий процент будет меняться по мере выдачи заданий,
а не окончания их обработки. Т.е. если дошло до 100%, а что-то ещё доделывается
- это нормально.

	3.9. Открытая админка на скорость работы демона влияет слабо.
Обновляет страницу примерно раз в 4 секунды, тогда как демон за 4 секунды
обрабатывает в десятки раз больше страниц. Точное число зависит от числа потоков
и свойств серверов сайтов. Сумма просмотренных страниц отображается
около общего процента.

	3.10. Текущая позиция обрабатываемого файла находится в файле
<папка_сайта>/formcrawler/src/src_pos.php
Для того, чтобы начать обработку всех сайтов с начала - надо его удалить.

4. Решение возможных проблем

	4.1. Если админка не работает, то донастроить сайт.

	4.2. Если демон не стартует через админку.
Попробовать запустить из консоли.
Для этого надо перейти в папку сайта и выполнить
php -f formcrawler_daemon.php

	4.3. Если демон не стартует через админку, но стартует из консоли.
Разрешить PHP-функции exec,popen,pclose (см. пункт 2.2).

	4.4. Если демон не стартует ни через админку, ни из консоли.
Прочесть ошибки PHP. Убедиться, что установлен и включен libevent (см. пункт 2.2).

	4.5. Если демон запускается и через некоторое время останавливается,
и ещё нормально на этом сервере не работал.
4.5.1. Проверить, есть ли исходный файл с заданиями. Создать.
4.5.2. Проверить, разрешён ли доступ на запись ко всем папкам. Разрешить.
4.5.3. Проверить, используются ли для демона разрешённые порты (см. пункт 2.6.)

	4.6. Если демон запускается и через некоторое время останавливается,
а раньше уже нормально работал.
4.6.1. Может кто-то ещё его остановил?
4.6.2. Может не хватило оперативной памяти и он заглючил - уменьшите число потоков.
4.6.3. Возможно встретилось задание, которое демон некорректно обрабатывает.
1) Выставите число потоков в 1

2) Зайдите в папку
<папка_сайта>/formcrawler/jbs/
Посмотрите наличие файлов. Это файлы заданий.
Если файлов несколько - можно выяснить, какой именно вызывает ошибку.

3) Запустите демон. Если до остановки админка успевает написать номер задания
в графе pos - этот номер нужно запомнить (например, по последним 3-4 цифрам).

4) Номер pos задания совпадает с началом имени файла задания.
Если перенести его в другую папку и прислать нам - исправим обработку.
Если удалить файл задания, вызывающего остановку демона,
это временно решит проблему. Если до остановки демон не успел написать
номер задания, можно предположить, что это это первое задание по порядку.
Попробуйте поступить также с ним.

5) Снова запустите демон. Если пошло без остановок,
выставите предпочтительное число потоков.

Примечание 1. Для ускорения идентификации задания, вызывающего глюк,
нужно выставлять число потоков, чуть меньшее числа файлов в каталоге с заданиями.
Как только число потоков и файлов сравняется, можно выставлять 1 поток.

Примечание 2. Подозрения должны в первую очередь падать на задания,
в которых v=1, t=0. Попробуйте исключить их по одному.

Примечание 3. Папка с заданиями читается только при старте демона.

	4.7. Демон запущен, но работы не выполняются.
	
1) Все работы завершены? 100%? Значит, работа завершена, и следует открыть файл отчёта - <папка_сайта>/formcrawler/res/FormsFound.txt
2) 0 потоков? Установите количество потоков, больше 0, и нажмите на "Set"
3) Возможно встретилось задание, которое обрабатывается некорректно. Обратитесь к разработчику, с указанием ссылки/домена, кот. обрабатывается некорректно. Действуйте по инструкции 4.6.3.