تشغيل عُقدة OpenFiat

1. 01

   جهّز الجهاز

   خادم Debian أو Ubuntu حديث، وجدار حماية، وساعة دقيقة. الساعة أهم مما تبدو: تحمل السجلات طوابع زمنية وأوقات انتهاء، وساعة منحرفة تجعل العُقدة ترفض بيانات صالحة.

   shellنسخ

   # Debian 12 / Ubuntu 24.04, as root
   apt update && apt install -y ca-certificates curl gnupg ufw chrony
   
   # Clock drift breaks signature and expiry checks — keep NTP running.
   systemctl enable --now chrony

2. 02

   ثبّت العُقدة

   ابنِ من المصدر وشغّل الناتج تحت systemd — لم يُوسَم أي إصدار بعد، فتلك الطريقة الوحيدة للحصول على ملف ثنائي اليوم، وبقية هذا الدليل يفترضها. لا تلجأ إلى Docker إلا عند الاختبار محليًا أو رفع عنقود قابل للتخلّص.
3. 03

   ولّد محفظة العُقدة

   لا يوجد تنسيق "هوية عُقدة" منفصل — هوية العُقدة هي wallet.json حقيقي من CLI الخاص بـ Solana، الملف نفسه الذي ينتجه solana-keygen. تُعاد بذرته لكلٍّ من هوية gossip/النِدّ للعُقدة ومفتاح توقيع Solana. احتفظ بالملف — إن فقدته تعود العُقدة كغريب وتبدأ بناء السمعة من الصفر.

   shellنسخ

   # The node's identity IS a Solana CLI-format wallet.json — the same
   # file "solana-keygen new" produces (its own seed is reused for the
   # node's gossip/P2P keypair too, see crates/cli's load_or_generate_wallet).
   # There is no separate "node identity" format or command.
   solana-keygen new --outfile /etc/openfiat/wallet.json
   chmod 600 /etc/openfiat/wallet.json
   solana-keygen pubkey /etc/openfiat/wallet.json

4. 04

   اضبط البيئة

   openfiat-node ليس له ملف إعداد خاص — كل ضبط متغيّر بيئة، يُقرأ مرة عند البدء: أين تعيش البيانات، وأي عنوان للإصغاء، وأي أنداد لطلبهم عند البدء، و(اختياريًا) أي نقطة نهاية RPC لـ Solana يُستخدَم. يجب أن تكون أنداد الإطلاق multiaddr/IP ثابتًا، لا اسم مضيف — إطلاق DNS لا يُحلّ.

   shellنسخ

   # There is no config file and no environment variables. Every
   # setting is a flag on the systemd unit's ExecStart below, so
   # "systemctl cat openfiat-node" shows exactly what a running node was
   # given, and "openfiat-node --help" is the whole surface.
   #
   # Try it in the foreground first — the node prints the addresses it is
   # reachable at and whether it reached Solana:
   
   openfiat-node \
     --ledger /var/lib/openfiat \
     --identity /etc/openfiat/wallet.json \
     --rpc-bind-address 0.0.0.0:7080 \
     --gossip-bind-address /ip4/0.0.0.0/udp/4001/quic-v1 \
     --entrypoint /ip4/84.32.223.111/udp/4001/quic-v1/p2p/12D3KooWK9hQ7TwbfvFiaAxUbRFCkdhS7iEpAJDnewNL1anyREQ1 \
     --solana-rpc-url https://api.devnet.solana.com
   
   # Omit --solana-rpc-url to stay GossipOnly, the safe default: the node
   # still serves the marketplace, but its on-chain answers come
   # second-hand from peers. Never put a real endpoint or API key anywhere
   # version controlled — it belongs in the unit file on the server.
   #
   # Add --ipfs-api-url http://127.0.0.1:5001 to pin protocol content and
   # earn the full reward share, and --retention archival to keep the whole
   # history instead of a rolling 30 days.

5. 05

   افتح المنافذ الصحيحة

   يصل الأنداد إلى العُقدة عبر UDP لأن QUIC هو النقل الأساسي — ذلك المنفذ الذي ينساه الناس أكثر. منفذ TCP واحد يخدم JSON-RPC وWebSocket وREST والصحة والمقاييس معًا؛ أبقِه خاصًا إن لم ترد خدمة العملاء علنًا.

   shellنسخ

   ufw default deny incoming
   ufw allow 22/tcp                 # keep your own access
   ufw allow 4001/udp               # libp2p, QUIC — the port people most often forget
   ufw allow 443/tcp                # once nginx terminates TLS in front (see below)
   ufw allow 7080/tcp               # only if the node is exposed directly, without a proxy
   ufw enable && ufw status verbose

6. 06

   اخدم الشبكة: اجعل عُقدتك قابلة للوصول

   هذه الخطوة التي تحوّل العُقدة من شيء يراقب الشبكة إلى شيء يحملها. ضع nginx في المقدمة واحصل على شهادة، ثم أخبر العُقدة بعنوانها العام عبر --public-rpc-url فتُعلن عن نفسها لتستطيع المحافظ والمستكشفات وتطبيق OpenFiat الخاص استخدامها. الترتيب مهم: nginx على HTTP عادي أولًا، ثم certbot يضيف TLS — إعداد يسمّي شهادة أصلًا لا يستطيع البدء، فيفشل certbot قبل أن يصدر التي كانت ستُصلحه. الشهادة ليست زينة اختيارية: صفحة تُخدَم عبر HTTPS لا تستطيع فتح اتصال HTTP عادي، فعُقدة بلا واحدة غير مرئية لكل متصفّح مهما كانت سليمة.

   /etc/nginx/sites-available/openfiat-nodeنسخ

   # /etc/nginx/sites-available/openfiat-node
   #
   # HTTP only at this stage, with NO TLS directives. certbot --nginx works
   # by running "nginx -t" and editing this file, so a config that already
   # points at a certificate cannot load, nginx will not start, and certbot
   # fails before it can issue the certificate that would have fixed it.
   server {
       listen 80;
       listen [::]:80;
       server_name openfiat.example.com;
   
       location / {
           proxy_pass http://127.0.0.1:7080;
           proxy_http_version 1.1;
   
           # The node serves its WebSocket event stream on the same port;
           # without these the stream downgrades to a plain request and
           # subscriptions silently never deliver.
           proxy_set_header Upgrade    $http_upgrade;
           proxy_set_header Connection "upgrade";
   
           proxy_set_header Host              $host;
           proxy_set_header X-Real-IP         $remote_addr;
           proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
   
           # Do NOT add CORS headers here — the node already sets them, and
           # two Access-Control-Allow-Origin headers on one response make
           # browsers reject it while curl sees a clean 200.
           proxy_read_timeout 300s;
       }
   }

   shellنسخ

   # The A record must already resolve for the world — certbot proves
   # control of the name over port 80. Check a public resolver, not your
   # own machine, whose cache can be stale:
   dig +short @8.8.8.8 openfiat.example.com
   
   ln -s /etc/nginx/sites-available/openfiat-node /etc/nginx/sites-enabled/
   nginx -t && systemctl reload nginx
   curl -s http://openfiat.example.com/health    # ok, before any certificate
   
   apt install -y certbot python3-certbot-nginx
   certbot --nginx -d openfiat.example.com
   
   # certbot edits the server block in place: it adds listen 443 ssl, the
   # certificate paths, and a redirect from :80. The location block and its
   # proxy headers carry over. Renewal installs itself as a systemd timer.
   # Do not hand-write a 443 block afterwards — certbot manages that one.
   
   # Then tell the network this node can be reached directly:
   #   openfiat-node --public-rpc-url https://openfiat.example.com

7. 07

   شغّلها كخدمة

   تحت systemd تُعاد العُقدة بعد تعطّل أو إعادة تشغيل، وتحصل على فترة سماح إيقاف طويلة كفاية لتفرّغ قاعدة البيانات نظيفة بدلًا من قتلها في منتصف الكتابة.

   openfiat-node.serviceنسخ

   # /etc/systemd/system/openfiat-node.service
   [Unit]
   Description=OpenFiat node
   Documentation=https://docs.openfiat.network
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=openfiat
   Group=openfiat
   ExecStart=/usr/local/bin/openfiat-node \
       --ledger /var/lib/openfiat \
       --identity /etc/openfiat/wallet.json \
       --rpc-bind-address 0.0.0.0:7080 \
       --gossip-bind-address /ip4/0.0.0.0/udp/4001/quic-v1 \
       --entrypoint /ip4/84.32.223.111/udp/4001/quic-v1/p2p/12D3KooWK9hQ7TwbfvFiaAxUbRFCkdhS7iEpAJDnewNL1anyREQ1 \
       --solana-rpc-url https://api.devnet.solana.com
   WorkingDirectory=/var/lib/openfiat
   Restart=on-failure
   RestartSec=5s
   
   # openfiat-node handles SIGTERM itself (graceful shutdown) rather than
   # needing systemd to force-kill it; this gives that shutdown path a
   # reasonable window before systemd escalates to SIGKILL.
   TimeoutStopSec=30s
   
   NoNewPrivileges=true
   ProtectSystem=strict
   ProtectHome=true
   ReadWritePaths=/var/lib/openfiat
   PrivateTmp=true
   
   # AF_NETLINK is required, not optional: binding a wildcard address makes
   # libp2p enumerate this host's interfaces, and that goes over a netlink
   # socket. Without it the QUIC listener fails and the gossip actor panics
   # while the HTTP thread survives — so systemd reports the unit active
   # and the node looks healthy while serving nothing.
   RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
   
   [Install]
   WantedBy=multi-user.target

   shellنسخ

   useradd --system --create-home --home-dir /var/lib/openfiat --shell /usr/sbin/nologin openfiat
   install -m 755 openfiat-node /usr/local/bin/openfiat-node
   mkdir -p /etc/openfiat
   chown -R openfiat:openfiat /var/lib/openfiat
   
   systemctl daemon-reload
   systemctl enable --now openfiat-node
   journalctl -u openfiat-node -f

8. 08

   دعها تلحق

   بدلًا من إعادة تشغيل كل التاريخ، تستطيع عُقدة جديدة اكتشاف واستيراد لقطة معلَنة من نِدّ لحالة السوق الحالية (OFS-1300) — طرق JSON-RPC حقيقية، لا أداة منفصلة: getLatestSnapshot، getCheckpointHeight. التوقيع وإصدار البروتوكول وجذر الحالة كلها عليها أن تتطابق قبل الوثوق بها.

   shellنسخ

   # Snapshot sync (OFS-1300) is real JSON-RPC, not a separate CLI —
   # a new node discovers and imports a peer-announced snapshot instead of
   # replaying all history:
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getLatestSnapshot","params":{}}'
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getCheckpointHeight","params":{}}'

9. 09

   تحقّق من أنها سليمة

   GET /health يؤكّد أن العملية قائمة؛ وgetChainStatus عبر JSON-RPC يخبرك إن كانت GossipOnly أم RpcConnected، وblockhash الحالي إن كانت الأخيرة.

   shellنسخ

   # Is it up, and which mode is it in?
   curl -s http://localhost:7080/health
   # ok
   
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getChainStatus","params":{}}'
   # {"jsonrpc":"2.0","id":1,"result":{"mode":"GossipOnly","blockhash":null,"slot":null,"age_ms":null}}
   # ("RpcConnected" with a real blockhash once --solana-rpc-url is set)
   
   # The addresses your node is reachable at are in its own log — give one
   # of these to another operator as their --entrypoint:
   journalctl -u openfiat-node | grep "reachable at a new address"

10. 10

    هي أصلًا جزء من الشبكة

    لا خطوة "إعلان" منفصلة — بمجرد أن يكون للعُقدة أنداد إطلاق، تنشر عبر gossip ويُنشَر عنها تلقائيًا؛ لا أحد يوافق عليها. الرهن ونشر بيانات سجل الخدمات والانضمام إلى النزاعات وإلقاء أصوات الحوكمة كلها إجراءات منفصلة يقودها المحفظة يؤدّيها عميل مقابل العُقدة العاملة — راجع دليل المشاركة المناسب لكلٍّ منها.

    ترهن العُقدة OPEN لتصبح مشاركًا نشطًا. لكن الرهن لا يشتري سمعة: مشغّل ذو أداء ضعيف لا يستطيع التعويض برهن أكثر. تجمع الأولوية الفعّالة بين السمعة والرهن وأداء الشبكة المُقاس.
11. 11

    راقبها

    الإشارات التي تتنبّأ فعلًا بالمشكلات هي الأنداد المتصلون، ووضع السلسلة (GossipOnly مقابل RpcConnected)، وعمر blockhash. نبّه على هذه فتعرف قبل مستخدميك.

    prometheus.ymlنسخ

    # /etc/prometheus/prometheus.yml — same port as everything else,
    # no separate metrics listener to configure on the node's own side.
    scrape_configs:
      - job_name: openfiat-node
        static_configs:
          - targets: ["127.0.0.1:7080"]

12. 12

    أبقِها محدّثة

    أوقف، استبدل الملف الثنائي، ابدأ. تُحدَّث العُقد واحدة تلو الأخرى، فلا تحتاج الشبكة أبدًا إلى انقطاع منسّق، وتُعاد أحداث gossip المفقودة عند البدء.

    shellنسخ

    systemctl stop openfiat-node        # SIGTERM, lets RocksDB flush
    # docker: docker compose pull node && docker compose up -d node
    install -m 0755 ./openfiat-node /usr/local/bin/
    systemctl start openfiat-node
    
    # Missed gossip events replay automatically on start.
    journalctl -u openfiat-node -f

13. 13

    انسخ ما لا يمكن إعادة توليده

    يمكن دائمًا إعادة مزامنة حالة السوق من لقطة. المحفظة لا يمكن إعادة توليدها. الأرصدة والضمان تعيش على Solana، لا على قرصك.

    shellنسخ

    # Back up what cannot be re-derived. Marketplace state can always be
    # re-synced from a snapshot; the wallet cannot be regenerated.
    tar czf openfiat-wallet-$(date +%F).tar.gz /etc/openfiat/wallet.json
    
    # Authoritative financial state lives on Solana, not on the node's own
    # RocksDB volume.

تعرض كل عُقدة مطابِقة سطح API نفسه، فواجهة مكتوبة مقابل عُقدة واحدة تعمل مقابلها جميعًا.