Exécution d’un bot de messagerie sur OpenWrt

Pourquoi cette note existe

OpenWrt est généralement traité comme un firmware routeur, pas comme un serveur d'applications général.

Un service d'automatisation de messagerie est un bon exemple d'une charge de travail qui peut fonctionner en continu sans avoir besoin d'un VPS complet.

Cette note documente le côté pratique de l'exécution d'un petit service de messagerie Node.js sur OpenWrt: où placer les fichiers, comment gérer les variables d'environnement, comment le faire fonctionner comme un service, comment le redémarrer, et comment déboguer les problèmes de déploiement communs.

Le point n'est pas que le bot fonctionne sur OpenWrt parce que c'est impressionnant. Le point est d'apprendre à exploiter un petit service sur une infrastructure limitée sans perdre la trace des journaux, secrets, mises à jour et redémarrages.

Contexte du périphérique

La configuration est basée sur un appareil OpenWrt utilisé à la fois comme infrastructure réseau et comme hôte de service léger.

Dans ce type de configuration, le routeur est déjà important. Ajouter des services d'application signifie un soin supplémentaire est nécessaire.

Le service ne devrait pas rendre le routeur plus difficile à maintenir, et les défaillances de bot ne devraient pas affecter le routage, le DNS, le VPN ou le comportement du pare-feu.

Ce que cette configuration veut prouver

petits services peuvent fonctionner sur OpenWrt lorsque l'appareil a suffisamment de ressources
les services hébergés par le routeur ont besoin d'un redémarrage et d'une gestion du journal propres
Les variables d'environnement ne doivent pas être codées en code source
Docker peut faire des mises à jour plus propres, mais il ajoute sa propre couche opérationnelle
OpenWrt procd peut exécuter les services directement lorsque Docker n'est pas nécessaire
les scripts de déploiement réduisent les commandes manuelles répétées
les journaux sont essentiels parce que les pannes de robots silencieuses sont fréquentes
l'hébergement de service sur un routeur doit rester délibéré et limité

Pioche et outils utilisés

Couche d'application

Numéro.js
discord.js
JavaScript
variables environnementales
configuration du jeton bot
Gestion des commandes/événements

Couche ouverte

SSH
LuCI où utile
gestion des paquets
chemins du système de fichiers sous /opt
gestion des services
logs via l'outil OpenWrt
sensibilisation au stockage/au recouvrement

Couche de déploiement

Docker, facultatif
procd, en option
.env.local ou un fichier d'environnement équivalent
scripts build/run/stop/restart
Processus de mise à jour basé sur Git ou sur copie
SCP/rsync ou autre méthode de synchronisation

Dépannage du calque

container logs
registres des services
contrôle des processus
contrôle des fichiers environnementaux
Contrôles d'enregistrement de la commande Discord
validation du temps réseau/DNS

Construction prévue

La construction prévue est un petit service de bot qui peut fonctionner en continu sur OpenWrt et être maintenu sans répéter manuellement un long ensemble de commandes à chaque fois.

Une configuration terminée devrait permettre :

code source stocké dans un répertoire clair
secrets stockés en dehors du code
démarrage/arrêt/redémarrage prévisible
journaux disponibles lorsque le bot échoue
facile à reconstruire ou à redéployer
mise à jour claire flux de travail de la machine de développement à OpenWrt
récupération de service après redémarrage
impact minimal sur les fonctions du routeur central

Présentation du répertoire

Un aménagement propre est important.

Exemple de direction:

/opt/discord-bots/
  bot-name/
    package.json
    src/
    .env.local
    scripts/

Le nom exact du robot peut changer, mais le principe reste le même :

les fichiers d'application vivent dans un répertoire connu
secrets ne sont pas commis publiquement
scripts en direct près du projet
les journaux sont faciles à atteindre
le chemin de déploiement est documenté

Variables d'environnement

Les secrets ne devraient pas être codés en dur.

Un fichier d'environnement local peut stocker des valeurs comme :

DISCORD_TOKEN=
CLIENT_ID=
GUILD_ID=
NODE_ENV=production

Le bot doit charger le fichier d'environnement au démarrage.

Contrôles importants:

le fichier existe sur OpenWrt
le service/conteneur peut le lire
les noms de variables correspondent au code
le jeton n'est pas imprimé dans les journaux
le fichier n'est pas engagé dans un dépôt public

Un fichier env manquant ou illisible est l'une des façons les plus faciles pour un bot de échouer après le déploiement.

Courir directement avec Node.js

Une direction est d'exécuter le robot directement avec Node.js installé sur OpenWrt.

Cela maintient la configuration simple, mais dépend de l'environnement du paquet OpenWrt et de la version Node.js installée.

Forme manuelle de base:

node src/index.js

Pour la production, l'exécution manuelle ne suffit pas. Le robot doit fonctionner comme un service géré.

Courir avec OpenWrt procd

Les services OpenWrt utilisent normalement procd.

Un service procd peut :

Démarrer le robot au démarrage
redémarrer si elle s'écrase
capture stdout/stderr
faciliter le démarrage/arrêt/redémarrage
intégrer avec les commandes de service OpenWrt

Exemple de forme de service :

#!/bin/sh /etc/rc.common

START=99
STOP=10
USE_PROCD=1

APP_DIR="/opt/discord-bots/bot-name"

start_service() {
  procd_open_instance
  procd_set_param command /usr/bin/node "$APP_DIR/src/index.js"
  procd_set_param env NODE_ENV=production
  procd_set_param respawn 3600 5 5
  procd_set_param stdout 1
  procd_set_param stderr 1
  procd_close_instance
}

Ceci devrait être adapté à la méthode réelle de chargement du projet et de l'environnement.

Courir avec Docker

Docker est utile lorsque vous voulez un temps d'exécution plus cohérent.

Une configuration Docker peut définir la version Node.js, les dépendances, l'utilisation des fichiers d'environnement et le comportement de redémarrer plus proprement.

Exemple de direction:

Dockerfile
.env.local
docker build
docker run --env-file .env.local

Pour OpenWrt, le support Docker dépend des ressources du périphérique, du stockage, du support du noyau et de la disponibilité du paquet.

Docker rend l'emballage d'application plus propre, mais il ajoute également:

image reconstruite
nettoyage du contenant
Manipulation du volume/env
container logs
décisions de mise en réseau
utilisation du stockage

Choix de réseau Docker

Pour un petit robot, le réseau hôte peut être simple :

--network host

Cela évite une certaine complexité du réseau de conteneurs, mais il devrait être utilisé intentionnellement.

Le robot n'a généralement besoin que d'un accès sortant à Discord, donc il n'a pas besoin de ports publics entrants.

Gestion des services et des conteneurs

Un déploiement utile devrait inclure des scripts pour des actions communes.

Exemples:

build
run
stop
restart
logs
status
clean
help

Le but est d'éviter de se souvenir de longues commandes Docker ou service manuellement.

Un script d'aide devrait être suffisamment clair pour que les mises à jour futures ne soient pas douloureuses.

Déploiement

Un workflow pratique ressemble à ceci :

modifier le code sur la machine de développement
essai local si possible
synchroniser les fichiers vers OpenWrt
installer des dépendances ou reconstruire un conteneur
redémarrer le service/conteneur
vérifier les journaux
vérifier que le robot est en ligne
tester une commande/action réelle

La synchronisation de fichier peut utiliser :

scp
rsync
Git pull si disponible
téléchargement manuel pour les petits changements

La méthode exacte importe moins que la cohérence.

Points communs de défaillance

Le service démarre localement mais pas sur OpenWrt

Causes probables:

mauvaise version Node.js
dépendances manquantes
mauvais répertoire de travail
.env.local manquant
permissions de fichier
Différences de chemin ouvertes
service ne charge pas les variables d'environnement

Conteneur construit mais ne fonctionne pas

Causes probables:

Mauvaise architecture d'image
commande manquante
fichier env manquant
mauvais nom du conteneur
vieux conteneur existe déjà
défaillance de l'installation de la dépendance
l'application sort immédiatement

Contrôles utiles:

docker ps -a
docker logs <container-name>

Le service est actif mais les commandes sont erronées

Causes probables:

Enregistrement de commandement non redéployé
des noms de commande dupliqués
commandes enregistrées globalement mais attendues instantanément
anciennes commandes encore mises en cache
Mauvaise application/identifiant client
mauvaise identification de la guilde
bot manque de permissions

Le service fonctionne mais les journaux manquent

Causes probables:

stdout/stderr non capturé
fichier de service ne permet pas l'enregistrement
Registres des conteneurs non vérifiés
application capture les erreurs silencieusement
sortie du processus avant l'enregistrement

Erreurs de temps ou de certificat

Un appareil avec un temps de système incorrect peut causer des problèmes TLS/certificat.

Les symptômes peuvent sembler sans rapport, comme les demandes de réseau qui échouent même si le DNS et l'accès à Internet fonctionnent.

Contrôles utiles:

date
logread | grep -i cert

Si le temps est faux, corrigez d'abord la synchronisation NTP/time.

Décisions pratiques

Protéger l'emploi principal du routeur

Le routeur devrait être un routeur d'abord.

Si le bot devient lourd, instable ou compliqué, il peut être préférable de le déplacer vers un petit serveur ou un VPS.

Ne pas coder les secrets

Les jetons et les identifiants devraient vivre dans des fichiers d'environnement ou une manipulation secrète, et non dans le code.

Utiliser des scripts pour des actions répétées

Si une commande est répétée souvent, faites-en un script.

Cela réduit les erreurs pendant la reconstruction, le redémarrage et le nettoyage.

Préférez effacer les journaux sur les redémarrages silencieux

Un service qui redémarre automatiquement mais ne donne pas de journaux utiles est difficile à maintenir.

Les journaux devraient rendre les échecs évidents.

Évitez d'exposer inutilement les ports

La plupart des services d'automatisation de messagerie ont seulement besoin d'un accès sortant.

N'ouvrez pas les ports publics à moins que le bot n'exécute un serveur web ou un auditeur webhook qui a réellement besoin de trafic entrant.

Gardez une source propre de vérité de déploiement

Évitez d'avoir plusieurs méthodes de déploiement en même temps.

Si Docker est utilisé, faites Docker le chemin principal. Si procd direct Node.js est utilisé, faites que le chemin principal.

Ce qu'une configuration terminée devrait montrer

Une configuration solide devrait montrer:

fichiers source bot dans un répertoire clair
fichier environnement présent et protégé
service/conteneur démarre de manière fiable
redémarrer le workflow documenté
journaux disponibles
bot vient en ligne après redémarrage ou redémarrage
script de déploiement/mise à jour disponible
enregistrement des commandes compris
aucun port public inutile exposé
fonctions du cœur du routeur non affectées
processus de nettoyage pour les vieux contenants/images en utilisant Docker

Preuves à retenir

Voici quelques éléments de preuve utiles à cette note :

screenshot ou arborescence du répertoire
exemple de fichier de service
Dockerfile
script helper
.env.example sans véritables secrets
Sortie docker ps
État de service
exemples de journaux
capture d'écran en ligne bot
commande test screenshot
Essai de redémarrage
notes sur les échecs et les corrections

Hypothèses techniques

Cette configuration suppose que le périphérique OpenWrt a assez de processeur, de RAM et de stockage pour le bot et l'exécution.

Il suppose également que le robot est petit et principalement basé sur l'événement/commande, pas une application lourde.

La configuration suppose que l'accès Internet, DNS et le temps du système sont stables, car l'accès à l'API Discord dépend de tous les trois.

Principaux risques

routeur surchargé par les services d'application
secrets commis accidentellement ou imprimés
bot échoue silencieusement après le redémarrage
anciens conteneurs en conflit avec de nouveaux conteneurs
Mauvaise image d'architecture
variables d'environnement manquantes
stockage remplissage avec images/logs
DNS / problèmes de temps causant des pannes d'API
confusion dans l'enregistrement des commandes
pas de retour net après une mise à jour cassée

État actuel

Cette note représente la direction de déploiement et de maintenance d'un service d'automatisation de messagerie léger sur OpenWrt.

La leçon importante est que même un petit service d'automatisation a besoin d'une structure opérationnelle lorsqu'il fonctionne en continu : fichiers d'environnement, gestion de service, comportement de redémarrage, journaux et étapes de déploiement répétables.

Ceci se connecte directement à d'autres notes sur OpenWrt, Docker scripts, DNS, et le dépannage de service.

Ce que la présente note ne prétend pas

Cette note ne prétend pas qu'OpenWrt est toujours le meilleur endroit pour accueillir des robots.

Elle ne prétend pas que les services hébergés par les routeurs conviennent à chaque charge de production.

Elle ne prétend pas que Docker est obligatoire.

Le projet est mieux compris comme une note de déploiement pratique pour les petits services sur les infrastructures limitées.

À emporter pratique

L'exécution d'un bot sur OpenWrt ne concerne pas principalement le démarrage de node index.js.

La partie utile est la structure opérationnelle qui la entoure :

où les fichiers vivent
comment les secrets sont chargés
comment ça commence après le redémarrage
comment il redémarre après l'échec
où les journaux sont lus
comment les mises à jour sont déployées
Comment nettoyer les contenants cassés
comment éviter d'affecter l'emploi principal du routeur

C'est ce qui rend l'installation durable.