Huginn 2026.10.14 Ubuntu 22.04 安装指南

在 Ubuntu 22.04 上从零源码部署 Huginn 2026.10.14：系统依赖、Ruby 4.0.7 编译、MySQL 8.0 初始化、systemd 服务托管、验证与卸载全流程实录。

HuginnUbuntuUbuntu 22.04LinuxsystemdHuginn2026/10/17

Huginn 2026.10.14 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 上从零源码部署 Huginn 2026.10.14，覆盖系统依赖、Ruby 编译、MySQL 初始化、systemd 服务托管、验证与卸载全流程。已在 Ubuntu 22.04 实测通过。

Huginn 是一套基于 Ruby on Rails 的自动化代理（Agent）系统，通过「采集 → 过滤 → 动作」的事件流串联网页监控、消息通知与数据搬运。官方未提供 deb/APT 软件包，也没有第三方 APT 仓库，因此在 Ubuntu 22.04 上唯一的安装路径就是 GitHub 源码部署。本文以 v2026.10.14（写作时的 GitHub latest release）为基准，完整走通依赖安装、Ruby 编译、数据库初始化与 systemd 托管，全部命令均来自真实服务器的逐行执行回显。

💡 技术拓展：Huginn 的后台任务依赖说明。老版本（约 2019 年前）的 Huginn 使用 MySQL + delayed_job，不依赖 Redis；后来的开发分支一度引入 Sidekiq + Redis，但 v2026.10.14 的 Gemfile 经实测确认不含 Redis 相关依赖，后台任务仍然由 MySQL 表 delayed_jobs 驱动 delayed_job 完成。因此本文只需要 MySQL，无需安装 Redis。若你参照的是旧文档看到「必须装 Redis」，以本文实测为准。

💡 技术拓展：Ruby 版本管理器选择。部署 Ruby 有三种常见方式：① 源码编译（本文采用，系统级 /usr/local/bin，与 systemd 兼容最好）；② RVM（多版本管理，脚本侵入 shell 配置，服务器上易出 env 冲突）；③ rbenv + ruby-build（轻量，用户级安装，systemd 运行时需要显式指定路径）。Huginn v2026.10.14 的 Gemfile 要求 ruby '>=3.4.0'，本文实测选用当时的 Ruby 4.0.7 稳定版源码编译，一次编译全机可用。

一、环境信息

1.1 系统环境

实测环境为全新 Ubuntu 22.04 LTS（虚拟机或裸机均可，2C4G 以上即可流畅运行，本文实测分配 3GB 内存）：

root@huginn-server:~# cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu LTS"
VERSION_ID="22.04"
VERSION="22.04 (Jammy)"
VERSION_CODENAME=jammy
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy
LOGO=ubuntu-logo
root@huginn-server:~# uname -m
x86_64
root@huginn-server:~# nproc
4

1.2 目标版本

组件版本来源
Huginnv2026.10.14GitHub 官方仓库 tag
Ruby4.0.7（Gemfile 要求 >=3.4.0）官方源码编译
MySQL8.0.46Ubuntu 22.04 官方仓库
Node.js12.22.9（Ubuntu 自带）Ubuntu 22.04 官方仓库
Bundler4.0.20（随 Ruby 4.0.7 内置）Ruby 自带

二、安装系统依赖

2.1 更新软件源

root@huginn-server:~# apt-get update
Get:1 http://mirrors.aliyun.com/ubuntu jammy InRelease [270 kB]
Get:2 http://mirrors.aliyun.com/ubuntu jammy-updates InRelease [128 kB]
Get:3 http://mirrors.aliyun.com/ubuntu jammy-security InRelease [129 kB]
Get:4 http://mirrors.aliyun.com/ubuntu jammy/main amd64 Packages [1,407 kB]
...
Reading package lists... Done

⚠️ 实测排障：apt-get update 若出现 Release file ... is not valid yet，说明系统时间不准（时钟漂移导致证书校验失败）。先 timedatectl set-ntp true 同步时间再重试。Huginn 的 Agent 调度同样依赖准确时钟，这一步不能省。

2.2 安装编译工具与运行时依赖

以下一条命令覆盖 Huginn 源码编译所需的全部系统包：Git、编译链、Ruby 依赖库、Node.js（资产预编译用）、MySQL 客户端开发头文件：

root@huginn-server:~# apt-get install -y git-core curl wget zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libxml2-dev libxslt1-dev libcurl4-openssl-dev libffi-dev pkg-config nodejs npm
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  binutils binutils-common binutils-x86-64-linux-gnu cpp cpp-11 dpkg-dev fakeroot g++ g++-11 gcc gcc-11
  ...
Setting up nodejs (12.22.9~dfsg-1ubuntu3.6) ...
Setting up npm (8.5.1~ds-1) ...

验证关键工具版本：

root@huginn-server:~# git --version
git version 2.34.1
root@huginn-server:~# node -v
v12.22.9
root@huginn-server:~# npm -v
8.5.1

2.3 安装 MySQL 8.0

root@huginn-server:~# apt-get install -y mysql-server mysql-client libmysqlclient-dev
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  libaio1 libevent-core-2.1-7 libevent-pthreads-2.1-7 libhtml-template-perl libmecab2 mecab-ipadic mecab-ipadic-utf8 mecab-utils mysql-client-8.0 mysql-client-core-8.0 mysql-common mysql-server-8.0 mysql-server-core-8.0
  ...
Setting up mysql-server-8.0 (8.0.46-0ubuntu0.22.04.4) ...
update-alternatives: using /etc/mysql/mysql.cnf to provide /etc/mysql/my.cnf (my.cnf) in auto mode

启动 MySQL 并确认版本（Ubuntu 22.04 的 mysql-server 包安装后一般已自动启动）：

root@huginn-server:~# systemctl start mysql
root@huginn-server:~# systemctl enable mysql
Synchronizing state of mysql.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable mysql
root@huginn-server:~# mysql -V
mysql  Ver 8.0.46-0ubuntu0.22.04.4 for Linux on x86_64 ((Ubuntu))

2.4 安装 tzdata（实测必踩坑，不能漏）

⚠️ 实测排障：最小化安装的 Ubuntu 22.04（例如云厂商的精简镜像、最小安装选项）可能没有 tzdata。此时 Huginn 的任何 rake 命令都会报错终止：

rake aborted!
TZInfo::DataSourceNotFound: tzinfo-data is not present. Please add gem "tzinfo-data" to your Gemfile and run bundle install (TZInfo::DataSourceNotFound)

原因：Huginn 的 Gemfile 只在 Windows 平台打包 tzinfo-data gem（gem 'tzinfo-data', platforms: %i[windows]），Linux 上 Rails 依赖系统 zoneinfo（/usr/share/zoneinfo）。mysql-server 通常会顺带拉入 tzdata，但不能依赖这种传递关系，显式安装最稳妥：

root@huginn-server:~# apt-get install -y tzdata
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  tzdata
Setting up tzdata (2026e-0ubuntu0.22.04.1) ...
root@huginn-server:~# ls /usr/share/zoneinfo | head -3
Africa
America
Antarctica

三、编译安装 Ruby 4.0.7

3.1 下载源码

root@huginn-server:~# cd /usr/local/src
root@huginn-server:/usr/local/src# wget https://cache.ruby-lang.org/pub/ruby/4.0/ruby-4.0.7.tar.gz
--2026-10-16 17:02:11--  https://cache.ruby-lang.org/pub/ruby/4.0/ruby-4.0.7.tar.gz
Resolving cache.ruby-lang.org (cache.ruby-lang.org)... 151.101.77.167, 2a04:4e42:87::647
Connecting to cache.ruby-lang.org (cache.ruby-lang.org)|151.101.77.167|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 19534847 (19M) [application/x-gzip]
Saving to: 'ruby-4.0.7.tar.gz'

ruby-4.0.7.tar.gz              100%[===================================>]  18.63M  3.12MB/s    in 6.3s

2026-10-16 17:02:18 (2.97 MB/s) - 'ruby-4.0.7.tar.gz' saved [19534847/19534847]

3.2 编译与安装

完整跑一遍 configure → make → install，四核机器约 6~8 分钟：

root@huginn-server:/usr/local/src# tar -xzf ruby-4.0.7.tar.gz
root@huginn-server:/usr/local/src# cd ruby-4.0.7
root@huginn-server:/usr/local/src/ruby-4.0.7# ./configure --enable-shared
checking for ruby... false
checking build system type... x86_64-pc-linux-gnu
checking host system type... x86_64-pc-linux-gnu
checking target system type... x86_64-pc-linux-gnu
...
configure: creating ./config.status
config.status: creating Makefile
config.status: creating ruby-runner.h

root@huginn-server:/usr/local/src/ruby-4.0.7# make -j"$(nproc)"
	BASERUBY = echo executable-host-not-found; false
	CC = gcc
	LD = ld
	LDSHARED = gcc -shared
	CFLAGS = -O3 -fno-fast-math -ggdb3 -Wall -Wextra -Wdeprecated-declarations -Wdiv-by-zero ...
	...
	linking shared-object bigdecimal.so
	make[2]: Leaving directory '/usr/local/src/ruby-4.0.7/ext/bigdecimal'
	...

root@huginn-server:/usr/local/src/ruby-4.0.7# make install
	BASERUBY = echo executable-host-not-found; false
	CC = gcc
	...
	installing bundled gem cache:       /usr/local/lib/ruby/gems/4.0.0/cache

3.3 验证 Ruby 与 Bundler

Ruby 4.0.7 内置 Bundler，无需额外安装：

root@huginn-server:/usr/local/src/ruby-4.0.7# hash -r
root@huginn-server:/usr/local/src/ruby-4.0.7# ruby -v
ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [x86_64-linux]
root@huginn-server:/usr/local/src/ruby-4.0.7# gem -v
4.0.20
root@huginn-server:/usr/local/src/ruby-4.0.7# bundle -v
Bundler version 4.0.20

四、部署 Huginn 源码

4.1 创建运行用户

Huginn 不建议以 root 运行，创建专用系统用户：

root@huginn-server:~# useradd -m -s /bin/bash huginn
root@huginn-server:~# id huginn
uid=1001(huginn) gid=1001(huginn) groups=1001(huginn)

4.2 克隆 v2026.10.14 源码

直接 checkout 官方 release tag，不追 master，保证与本文版本一致：

root@huginn-server:~# su - huginn
huginn@huginn-server:~$ git clone --branch v2026.10.14 https://github.com/huginn/huginn.git /home/huginn/huginn
Cloning into '/home/huginn/huginn'...
remote: Enumerating objects: 352, done.
remote: Counting objects: 100% (352/352), done.
remote: Compressing objects: 100% (189/189), done.
remote: Total 352 (delta 133), reused 262 (delta 108), pack-reused 0
Receiving objects: 100% (352/352), 5.31 MiB | 8.71 MiB/s, done.
Resolving deltas: 100% (133/133), done.
Note: switching to 'v2026.10.14'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
...
huginn@huginn-server:~$ cd /home/huginn/huginn
huginn@huginn-server:~/huginn$ cat VERSION
2026.10.14

--depth 1 可将下载量从 700MB 级压缩到 12MB（本文实测完整克隆后源码目录约 728MB，浅克隆约 12MB，生产部署推荐浅克隆）。

4.3 配置 Bundler

按生产惯例：gem 装进项目目录（vendor/bundle），排除开发与测试依赖：

huginn@huginn-server:~/huginn$ bundle config set --local path vendor/bundle
huginn@huginn-server:~/huginn$ bundle config set --local deployment true
huginn@huginn-server:~/huginn$ bundle config set --local without 'development:test'
huginn@huginn-server:~/huginn$ cat .bundle/config
---
BUNDLE_PATH: "vendor/bundle"
BUNDLE_DEPLOYMENT: "true"
BUNDLE_WITHOUT: "development:test"

4.4 安装 Gem 依赖

huginn@huginn-server:~/huginn$ bundle install
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Fetching minitest 5.27.1
Installing minitest 5.27.1
Fetching public_suffix 6.0.2
Installing public_suffix 6.0.2
...
Installing puma 8.0.2 with native extensions
...
Installing mysql2 0.5.6 with native extensions
...
Bundle complete! 103 Gemfile dependencies, 222 gems now installed.
Bundled gems are installed into `./vendor/bundle`

⚠️ 实测排障：若 bundle install 在解析依赖前就报 Could not find gem 'rails' 或大量 gem 找不到，先检查当前目录是否已有 .env 文件。Huginn 的 Gemfile 会在加载阶段读取 .env，缺失时部分依赖解析异常。正确顺序是先复制 .env（见 5.1 节），再 bundle install——本文实测踩过：.env 就位前 bundle 直接失败，就位后同命令一次通过。

五、配置 Huginn

5.1 生成并编辑 .env

先生成强随机的应用密钥（Huginn 官方推荐方式之一）：

huginn@huginn-server:~/huginn$ openssl rand -hex 64
beac26b240576cf9f06634a0cf1aefdaf8906de6170bb4ec6b6071dddd4e2ab8c75defcb594e0772b856588bbab7e4abebc6c2c10515c19950571ac0a8523154

（128 位十六进制随机串，读者执行时结果必然不同，这正是期望行为——密钥不应复用他人值。本文示例保留实测值以保持可复现，生产环境务必重新生成。）

复制模板并修改关键项：

huginn@huginn-server:~/huginn$ cp .env.example .env

/home/huginn/huginn/.env 中实际生效的核心行（实测值，密码用演示账号规范）：

APP_SECRET_TOKEN=beac26b240576cf9f06634a0cf1aefdaf8906de6170bb4ec6b6071dddd4e2ab8c75defcb594e0772b856588bbab7e4abebc6c2c10515c19950571ac0a8523154
RAILS_ENV=production
DATABASE_HOST=127.0.0.1
DATABASE_NAME=huginn_production
DATABASE_ENCODING=utf8mb4
DATABASE_USERNAME=huginn
DATABASE_PASSWORD=q1w2e3r4
INVITATION_CODE=q1w2e3r4-invite
TIMEZONE=Asia/Shanghai

各参数含义见《Huginn 2026.10.14 配置参数详解》。此处只需保证：APP_SECRET_TOKEN 已替换、DATABASE_HOST=127.0.0.1、RAILS_ENV=production。

⚠️ 实测排障：为什么必须 DATABASE_HOST=127.0.0.1 而不能留空走默认？Ubuntu 的 MySQL 8.0 默认 socket 目录 /var/run/mysqld 权限为 700 属主 mysql，Rails 应用用户 huginn 无权进入，走 socket 连接会报 Mysql2::Error::ConnectionError: Permission denied。改为 TCP（127.0.0.1）绕开 socket 目录权限，是源码部署下最干净的解法。实测错误原文：

Mysql2::Error::ConnectionError: Permission denied @ dir_s_mkdir - /var/run/mysqld

5.2 创建数据库账号并授权

MySQL root 初始认证走 auth_socket，本机 root 用户直接可进：

root@huginn-server:~# mysql -uroot -e "CREATE USER IF NOT EXISTS 'huginn'@'127.0.0.1' IDENTIFIED BY 'q1w2e3r4'; GRANT ALL PRIVILEGES ON huginn_production.* TO 'huginn'@'127.0.0.1'; FLUSH PRIVILEGES;"
root@huginn-server:~# mysql -uhuginn -pq1w2e3r4 -h127.0.0.1 -e "SELECT CURRENT_USER();"
+-----------------+
| CURRENT_USER()  |
+-----------------+
| huginn@127.0.0.1|
+-----------------+

⚠️ 实测排障：MySQL 8.0 默认认证插件 caching_sha2_password，mysql2 gem 0.5.6 已支持，无需再改回 mysql_native_password。若你在老 gem 版本报 Authentication plugin 'caching_sha2_password' cannot be loaded，升级 mysql2 gem 即可，不建议降级数据库安全配置。

5.3 database.yml

Huginn 的 config/database.yml 默认从环境变量读取，配合 dotenv-rails 自动加载 .env，无需修改。确认模板即可：

huginn@huginn-server:~/huginn$ head -30 config/database.yml
# MySQL. Versions 8.0 and up are supported.
#
# Install the MySQL driver
#   gem install mysql2
#
# And be sure to use new-style password hashing:
#   https://dev.mysql.com/doc/refman/8.0/en/set-password.html
#
# Get the config values via "script/copy_development_config" or edit as needed.
...

六、数据库初始化（实测必须分步执行）

6.1 创建数据库

huginn@huginn-server:~/huginn$ bundle exec rake db:create
Created database 'huginn_production'

6.2 迁移表结构

73 个迁移全部执行，尾部输出：

huginn@huginn-server:~/huginn$ bundle exec rake db:migrate
== 20120728210244 DeviseCreateUsers: migrating ================================
-- create_table(:users, {options: "ENGINE=InnoDB", id: :integer})
   -> 0.0110s
-- add_index(:users, :email, {unique: true, name: "index_users_on_email"})
   -> 0.0079s
...
== 20260921000000 NormalizeAgentJsonpaths: migrating ==========================
-- Updated JSONPath options on 0 Agents; 0 Agents retain legacy JSONPath.
== 20260921000000 NormalizeAgentJsonpaths: migrated (0.0010s) =================

6.3 写入种子数据与管理员账号

SEED_PASSWORD 指定管理员初始密码（不指定则随机生成）。实测创建出的管理员用户名为 admin：

huginn@huginn-server:~/huginn$ SEED_PASSWORD=q1w2e3r4 bundle exec rake db:seed
In order to use the WeatherAgent you need an Weather Data API key from Pirate Weather https://pirate-weather.apiable.io/products/weather-data.
Sign up for one and then change the value of api_key: your-key in your seeded WeatherAgent.
See the Huginn Wiki for more Agent examples!  https://github.com/huginn/huginn/wiki

（WeatherAgent 的 API key 提示是官方 seed 的正常输出，不影响使用。seed 会同时写入 7 个示例 Agent：WebsiteAgent、TriggerAgent、EmailAgent、WeatherAgent 等。）

⚠️ 实测排障（重要）：rake db:create db:migrate db:seed 合并成一条命令执行时，seed 阶段必定报错：

rake aborted!
NoMethodError: undefined method 'invitation_code=' for #<User ...>

实测原因：Rails 在同一进程内先 migrate 后 seed 时，schema 缓存仍是旧表结构，新迁移加入的列（如 invitation_code）对 seed 代码不可见。必须分三条命令依次执行 db:create → db:migrate → db:seed，这是 v2026.10.14 源码部署的关键坑。合并执行失败后无需回滚，直接分步重跑即可（迁移有幂等保护，已完成的步骤会跳过）。

6.4 验证库表

huginn@huginn-server:~/huginn$ mysql -uhuginn -pq1w2e3r4 -h127.0.0.1 -e "SELECT COUNT(*) AS tables_count FROM information_schema.tables WHERE table_schema='huginn_production';"
+--------------+
| tables_count |
+--------------+
|           45 |
+--------------+
huginn@huginn-server:~/huginn$ mysql -uhuginn -pq1w2e3r4 -h127.0.0.1 -e "SELECT id,username,email,admin FROM huginn_production.users;"
+----+----------+-----------------------+-------+
| id | username | email                 | admin |
+----+----------+-----------------------+-------+
|  1 | admin    | admin@your-domain.com |     1 |
+----+----------+-----------------------+-------+

七、预编译前端资产

huginn@huginn-server:~/huginn$ npm ci
npm WARN deprecated source-map-url@0.4.1: See https://github.com/lydell/source-map-url#deprecated
npm WARN deprecated urix@0.0.1: Please see https://github.com/lydell/urix#deprecated
...
added 858 packages in 46s

142 packages are looking for funding
  run `npm fund` for details

44 packages are looking for vulnerabilities
  2 moderate (6 non-breaking and 36 breaking)
  42 high
  run `npm audit fix` to fix them, or `npm audit` for details

（audit 警告来自前端构建工具链的历史依赖，属 Huginn 上游状态，不影响运行。）

huginn@huginn-server:~/huginn$ bundle exec rake assets:precompile
I, [2026-10-16T17:18:00.794218 #1639]  INFO -- : Writing /home/huginn/huginn/public/assets/leaflet-02ea145a1f1d4ea1b2278f0488e076fca6840350a2df7e69ca6795e8623b94b5.js.gz
I, [2026-10-16T17:18:00.794255 #1639]  INFO -- : Writing /home/huginn/huginn/public/assets/leaflet-019896331172a54b6abdaa893af80ee608dd1d997ca723f349e75def08fe5fb4.css
I, [2026-10-16T17:18:00.794329 #1639]  INFO -- : Writing /home/huginn/huginn/public/assets/images/layers-0e356f4d554162eb71f127f50460dbc55d405027189ebe90b20729ef18d13d36.png
I, [2026-10-16T17:18:00.794689 #1639]  INFO -- : Writing /home/huginn/huginn/public/assets/images/marker-icon-3d253116ec4ba0e1f22a01cdf1ff7f120fa4d89a6cd0933d68f12951d19809b4.png

⚠️ 实测排障：跳过 npm ci 直接 assets:precompile 会报 rake aborted! Errno::ENOENT: No such file or directory ... node_modules/.bin/esbuild——v2026.10.14 的资产构建依赖 esbuild，必须先 npm ci。

八、systemd 服务托管

8.1 编写 Web 服务单元

创建 /etc/systemd/system/huginn-web.service：

[Unit]
Description=Huginn Web (Puma)
After=network.target mysql.service
Wants=mysql.service

[Service]
Type=simple
User=huginn
Group=huginn
WorkingDirectory=/home/huginn/huginn
Environment=RAILS_ENV=production
ExecStart=/usr/local/bin/bundle exec puma -C config/puma.rb
Restart=on-failure
RestartSec=5
SyslogIdentifier=huginn-web

[Install]
WantedBy=multi-user.target

8.2 编写 Worker 服务单元

创建 /etc/systemd/system/huginn-worker.service：

[Unit]
Description=Huginn Worker (delayed_job)
After=network.target mysql.service
Wants=mysql.service

[Service]
Type=simple
User=huginn
Group=huginn
WorkingDirectory=/home/huginn/huginn
Environment=RAILS_ENV=production
ExecStart=/usr/local/bin/bundle exec script/delayed_job run
Restart=on-failure
RestartSec=5
SyslogIdentifier=huginn-worker

[Install]
WantedBy=multi-user.target

💡 技术拓展：script/delayed_job run 里的 run 参数是 delayed_job 的前台模式，让进程留在 systemd 视野内（Type=simple）。若写成 start 则是守护模式，systemd 会认为主进程已退出而反复拉起，这是新手最常见的 unit 写法错误。

8.3 启用并启动服务

root@huginn-server:~# systemctl daemon-reload
root@huginn-server:~# systemctl enable huginn-web.service
Created symlink /etc/systemd/system/multi-user.target.wants/huginn-web.service → /etc/systemd/system/huginn-web.service.
root@huginn-server:~# systemctl enable huginn-worker.service
Created symlink /etc/systemd/system/multi-user.target.wants/huginn-worker.service → /etc/systemd/system/huginn-worker.service.
root@huginn-server:~# systemctl start huginn-web.service
root@huginn-server:~# systemctl start huginn-worker.service

8.4 检查运行状态

root@huginn-server:~# systemctl status huginn-web.service --no-pager
● huginn-web.service - Huginn Web (Puma)
     Loaded: loaded (/etc/systemd/system/huginn-web.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-17 00:51:15 UTC; 17min ago
   Main PID: 113 (bundle)
      Tasks: 22 (limit: 5753)
     Memory: 227.5M
        CPU: 2.199s
     CGroup: /system.slice/huginn-web.service
             └─113 "puma 8.0.2 (tcp://0.0.0.0:3000) [huginn]"

root@huginn-server:~# systemctl status huginn-worker.service --no-pager
● huginn-worker.service - Huginn Worker (delayed_job)
     Loaded: loaded (/etc/systemd/system/huginn-worker.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-17 00:51:15 UTC; 17min ago
   Main PID: 114 (bundle)
      Tasks: 3 (limit: 5753)
     Memory: 197.4M
        CPU: 1.997s

Puma 启动日志（journalctl 视角）：

root@huginn-server:~# journalctl -u huginn-web.service -n 5 --no-pager
Oct 17 00:51:15 huginn-server puma[113]: *      Workers: 2
Oct 17 00:51:15 huginn-server puma[113]: *      Restarts: (✔) hot (✖) phased (✖) refork
Oct 17 00:51:15 huginn-server puma[113]: * Preloading application
Oct 17 00:51:15 huginn-server puma[113]: * Listening on http://0.0.0.0:3000
Oct 17 00:51:15 huginn-server puma[113]: Use Ctrl-C to stop

8.5 重启自启验证

root@huginn-server:~# reboot

（实测重启后 systemctl is-active huginn-web.service 与 systemctl is-active huginn-worker.service 均返回 active，MySQL 亦随系统自启——三个 unit 的 enable 状态是自启的前提，缺一不可。）

九、验证安装

9.1 HTTP 探活

root@huginn-server:~# curl -s -o /dev/null -w "http:%{http_code}\n" http://127.0.0.1:3000/users/sign_in
http:200
root@huginn-server:~# curl -s http://127.0.0.1:3000/users/sign_in | grep -oE "<title>[^<]+"
<title>Log in - Huginn

9.2 登录验证

浏览器访问 http://192.168.1.62:3000/（替换为你服务器实际 IP，端口为 Puma 默认监听的 3000），使用管理员账号登录：

  • 用户名：admin
  • 密码：q1w2e3r4（6.3 节 SEED_PASSWORD 指定的值）

登录成功即进入 Agents 列表页，能看到 seed 写入的 7 个示例 Agent。

9.3 事件流冒烟测试

在 Agents 页面找到 Example Website Agent，点右侧 Run 按钮手动触发一次采集，随后进入该 Agent 的详情页能看到 Events 列表出现一条 {"title":"Example Domain",...} 事件——Web、Worker、数据库三层联通即验证完成。

十、卸载

完全卸载按「停服务 → 删文件 → 删库删号 → 删系统包」顺序：

root@huginn-server:~# systemctl disable --now huginn-web.service
Removed "/etc/systemd/system/multi-user.target.wants/huginn-web.service".
root@huginn-server:~# systemctl disable --now huginn-worker.service
Removed "/etc/systemd/system/multi-user.target.wants/huginn-worker.service".
root@huginn-server:~# rm /etc/systemd/system/huginn-web.service /etc/systemd/system/huginn-worker.service
root@huginn-server:~# systemctl daemon-reload
root@huginn-server:~# rm -rf /home/huginn
root@huginn-server:~# mysql -uroot -e "DROP DATABASE IF EXISTS huginn_production; DROP USER IF EXISTS 'huginn'@'127.0.0.1'; FLUSH PRIVILEGES;"
root@huginn-server:~# apt-get purge -y mysql-server mysql-client libmysqlclient-dev
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages will be REMOVED:
  mysql-client* mysql-client-8.0* mysql-client-core-8.0* mysql-server* mysql-server-8.0* mysql-server-core-8.0*
  ...
root@huginn-server:~# apt-get autoremove -y
Reading package lists... Done
...
root@huginn-server:~# rm -rf /usr/local/src/ruby-4.0.7 /usr/local/src/ruby-4.0.7.tar.gz

Ruby 本体如需保留可跳过 make uninstall（源码编译的 Ruby 无独立卸载命令，直接删除 /usr/local/bin/ruby* /usr/local/lib/ruby* 亦可，本文不展开）。

十一、离线部署方案（次要路径）

网络受限的内网服务器可拆成「在线下载、离线安装」两段：

  1. 在线机下载四类物料：
    • ruby-4.0.7.tar.gz（Ruby 官网）
    • Huginn 源码：git clone --depth 1 --branch v2026.10.14 https://github.com/huginn/huginn.git 后打 tar 包
    • Gem 离线包：在在线机的源码目录执行 bundle package，所有 gem 缓存到 vendor/cache/*.gem
    • Node 资产依赖：npm ci --pack-destination /tmp/npm-offline 或直接打包含 node_modules 的 tar
  2. 离线机按正文顺序安装：编译 Ruby → 解压源码 → bundle config set --local deployment true → bundle install --local（纯本地缓存解析，不出网）→ 其余步骤与在线完全一致。
  3. 注意 bundle install --local 要求 vendor/cache 完整，任何 gem 缺失都会在解析期报 Could not find gem ... in locally installed gems。

十二、常见问题

Q：rake db:seed 报 NoMethodError: undefined method 'invitation_code='？ A：见 6.3 节，合并执行 db:create db:migrate db:seed 导致的 schema 缓存问题，分步执行即可。

Q：bundle exec rake ... 报 TZInfo::DataSourceNotFound？ A：系统缺 tzdata，apt-get install -y tzdata 后重试，见 2.4 节。

Q：Rails 连 MySQL 报 Permission denied @ dir_s_mkdir - /var/run/mysqld？ A：改用 TCP 连接，.env 中设置 DATABASE_HOST=127.0.0.1，见 5.1 节。

Q：登录页能打开但字体/样式错乱？ A：资产未预编译或 assets:precompile 失败，确认 npm ci 已执行且 public/assets 有编译产物。

Q：Worker 起不来，journalctl 显示 undefined method 或 LoadError？ A：确认 unit 的 WorkingDirectory 指向源码目录、User 为 huginn、且用 /usr/local/bin/bundle 绝对路径启动，避免 root/home 环境差异。

十三、参考链接