Ubuntu 22.04 安装 AsmBB v3.0 指南

目标：在 Ubuntu 22.04 服务器上从零安装 AsmBB v3.0 论坛引擎，覆盖官方推荐的「Nginx + systemd 常驻」主方案与「Lighttpd spawn 派生」备用方案，含版本校验、setup 初始化与全部实测排障。本指南已在 Ubuntu 22.04.5 LTS + Nginx 1.18.0 + Lighttpd 1.4.63 环境逐条实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86-64）
Web 服务器：Nginx 1.18.0 (Ubuntu)（主方案）/ Lighttpd 1.4.63 (ssl)（备用方案）
论坛引擎：AsmBB v3.0 官方二进制包（构建日期 2023-06-06，manifest.uuid 3df85ed0b218e51a59fe3f02650ef7467050cc46）
站点目录：/var/www/asmbb，运行用户 www-data
引擎监听：Unix 套接字 /var/www/asmbb/engine.sock（常驻模式）
数据文件：/var/www/asmbb/board.sqlite（SQLite，WAL 日志模式）
端口：80（HTTP）；443（HTTPS，见本专栏组合实战篇）

环境核对回显：

root@forum:~# cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
root@forum:~# nginx -v
nginx version: nginx/1.18.0 (Ubuntu)

二、前置条件

x86 架构 Linux：官方二进制 engine 为 32 位 i386 ELF，官方要求 x86 Linux（32/64 位均可）。ARM 服务器无法直接运行本包。验证：

root@forum:~# file /var/www/asmbb/engine
/var/www/asmbb/engine: ELF 32-bit LSB executable, Intel 80386, version 1 (GNU/Linux), dynamically linked, interpreter ./ld-musl-i386.so, no section header

💡 技术拓展：interpreter ./ld-musl-i386.so 表示引擎的动态链接器是随包分发的 musl C 库、且用相对路径引用。同类静态化方案对比——

方案特点代表
完全静态链接单文件零依赖，体积大 Go 二进制
相对路径 PT_INTERP + 随包 musl 免装运行库、可换 libc，但启动目录敏感 AsmBB（本包）
系统动态链接 glibc 依赖系统版本多数 C/C++ 软件

本包采用第二种，由此产生「必须从站点目录启动引擎」的硬约束，见八、常见问题 8.1。

方案	特点	代表
完全静态链接	单文件零依赖，体积大	Go 二进制
相对路径 PT_INTERP + 随包 musl	免装运行库、可换 libc，但启动目录敏感	AsmBB（本包）
系统动态链接 glibc	依赖系统版本	多数 C/C++ 软件

支持 FastCGI 的 Web 服务器：本指南安装 Nginx（主方案）：

root@forum:~# apt-get install -y nginx
nginx is already the newest version (1.18.0-6ubuntu14.22).
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.

systemd（主方案托管引擎用）：Ubuntu 22.04 默认自带。
出网可达 asm32.info：本环境直连官方源下载成功，未走代理降级。
建议安装 sqlite3 命令行工具（备份与排障章节会用到）：apt-get install -y sqlite3。

三、版本选型说明

项目	值	来源
官方最新发行	v3.0（2023-06-06）	GitHub tag 页与官方发布公告实查（2026-11-02）
二进制包永久链接	`https://asm32.info/fossil/repo/asmbb/doc/trunk/install/asmbb.tar.gz`	官方 install.txt / 发布公告
本次获取包大小	1713357 字节	实测 `ls -la`
本次获取包 sha256	`1acc74541cf6e47b7b0edcb6fdf5d63a3cb18f750be047d6c3d5ebd5723d8859`	实测 `sha256sum`
版本指纹	manifest.uuid `3df85ed0b218e51a59fe3f02650ef7467050cc46`	包内 manifest.uuid
上一版	v2.9.1（2020-06-30，BBCode 崩溃修复）	GitHub tag 页
源码编译	需 FASM 自举编译（Fossil 主库 `asm32.info/fossil/asmbb/`）	官方仓库

解读：官方永久链接永远指向「最新官方构建」，包内文件时间戳即构建日期；生产部署应像本表一样记录下载当次的 sha256 与 manifest.uuid 以锁定版本。v3.0 与 v2.x 数据库结构不兼容，跨大版本升级需执行官方迁移 SQL，操作见《AsmBB 日常运维手册》升级章节。一般场景直接使用官方二进制包即可，无需源码编译。

四、方案A：Nginx + systemd 常驻部署（官方 VPS 推荐）

本章按官方 install.txt「Installation on VPS with nginx and systemd」路径实施：引擎由 systemd 常驻拉起、自监听 engine.sock，Nginx 以 fastcgi_pass 转发。

4.1 下载并校验官方二进制包

root@forum:~# mkdir -p /root/dl && cd /root/dl
root@forum:~/dl# curl -sSfL -o asmbb.tar.gz https://asm32.info/fossil/repo/asmbb/doc/trunk/install/asmbb.tar.gz
root@forum:~/dl# ls -la asmbb.tar.gz
-rw-r--r-- 1 root root 1713357 Nov  2 00:58 asmbb.tar.gz
root@forum:~/dl# sha256sum asmbb.tar.gz
1acc74541cf6e47b7b0edcb6fdf5d63a3cb18f750be047d6c3d5ebd5723d8859  asmbb.tar.gz

sha256 与「三、版本选型说明」记录值一致，可继续。

4.2 解压并部署到站点目录

root@forum:~/dl# tar -xvzf asmbb.tar.gz
asmbb/
asmbb/images/
asmbb/images/favicon.ico
asmbb/images/emoticons_light/
asmbb/images/emoticons_light/tongue.gif
asmbb/images/emoticons_light/smile.gif
...
asmbb/templates/Light/sqlite.css
asmbb/templates/Light/activity3.tpl
asmbb/templates/Light/atom_start.tpl
asmbb/templates/Light/main_html_start.tpl
asmbb/lighttpd.conf
asmbb/manifest.uuid

输出节选（实测首尾）。注意包内含符号链接（如 templates/Light/*.tpl -> ../Wasp/*.tpl），必须用 tar 在服务器上直接解压，先本地解包再 FTP 上传会丢失链接。

root@forum:~/dl# mkdir -p /var/www/asmbb
root@forum:~/dl# cp -a asmbb/. /var/www/asmbb/
root@forum:~/dl# chown -R www-data:www-data /var/www/asmbb
root@forum:~/dl# ls -la /var/www/asmbb/
total 3732
drwxr-xr-x 5 www-data www-data    4096 Nov  2 00:45 .
drwxr-xr-x 4 root     root        4096 Nov  2 00:14 ..
-rw-r--r-- 1 www-data www-data     106 Jun  6  2023 .htaccess
-rw-r--r-- 1 www-data www-data   13512 Jun  6  2023 License.txt
-rw-r--r-- 1 www-data www-data       0 Nov  2 00:15 asmbb_ipc.lock
-rw-r--r-- 1 www-data www-data       0 Nov  2 00:15 asmbb_queue.lock
-rw-r--r-- 1 www-data www-data  397312 Nov  2 00:44 board.sqlite
-rw-r--r-- 1 www-data www-data   32768 Nov  2 00:46 board.sqlite-shm
-rw-r--r-- 1 www-data www-data 1495592 Nov  2 00:46 board.sqlite-wal
-rwxr-xr-x 1 www-data www-data  157818 Jun  6  2023 engine
srw-rw-rw- 1 www-data www-data       0 Nov  2 00:45 engine.sock
drwxr-xr-x 5 www-data www-data    4096 Jun  6  2023 images
-rw-r--r-- 1 www-data www-data    6833 Jun  6  2023 install.txt
-rwxr-xr-x 1 www-data www-data  808756 Jun  6  2023 ld-musl-i386.so
-rwxr-xr-x 1 www-data www-data  861496 Jun  6  2023 libsqlite3.so
-rw-r--r-- 1 www-data www-data    1204 Jun  6  2023 lighttpd.conf
-rw-r--r-- 1 www-data www-data      41 Jun  6  2023 manifest.uuid
drwxr-xr-x 8 www-data www-data    4096 Jun  6  2023 templates

（上为部署完成后目录全貌，board.sqlite*、engine.sock、asmbb_*.lock 为引擎首次运行后自动生成，全新安装时不存在。）官方 install.txt 硬性要求：文件属主为 Web 服务器用户 www-data 且站点目录可写（引擎要在原地创建数据库），可执行文件 755。

4.3 配置 systemd 托管引擎

创建 /etc/systemd/system/asmbb.service（按官方模板，把 WantedBy 调整为 multi-user.target 以便独立开机自启）：

[Unit]
Description=AsmBB forum engine FastCGI script.
After=nginx.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/asmbb
ExecStart=/var/www/asmbb/engine
Restart=on-failure

[Install]
WantedBy=multi-user.target

逐项说明：WorkingDirectory 是本方案最关键的一行——引擎的 PT_INTERP 是相对路径 ./ld-musl-i386.so，工作目录必须是站点目录，否则报「No such file or directory」（见 8.1）；Restart=on-failure 让引擎被杀后由 systemd 自动拉起（排障实录见运维手册）；User=www-data 保证新建的 board.sqlite/engine.sock 属主正确。

root@forum:~# systemctl daemon-reload
root@forum:~# systemctl start asmbb
root@forum:~# systemctl enable asmbb
root@forum:~# systemctl status asmbb
● asmbb.service - AsmBB forum engine FastCGI script.
     Loaded: loaded (/etc/systemd/system/asmbb.service; disabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-11-02 00:15:31 UTC; 9min ago
   Main PID: 3214 (engine)
      Tasks: 2 (limit: 2506)
     Memory: 3.1M
        CPU: 66ms

输出节选（实测首尾）。Tasks: 2、Memory: 3.1M 已能看出引擎的资源姿态：单进程、个位数 MB 常驻。

验证套接字与进程：

root@forum:~# ls -l /var/www/asmbb/engine.sock
srw-rw-rw- 1 www-data www-data 0 Nov  2 00:15 /var/www/asmbb/engine.sock
root@forum:~# ps -eo pid,user,rss,vsz,cmd | grep [e]ngine
   3214 www-data  2664   3208 /var/www/asmbb/engine

引擎自建 engine.sock 并置权限 666（源码 source/fcgi.asm 行为），srw-rw-rw- 即 Unix 套接字标志。

4.4 配置 Nginx FastCGI 转发

创建 /etc/nginx/sites-available/asmbb：

server {
    listen 80 default_server;
    server_name _;

    root /var/www/asmbb;

    location / {
        fastcgi_pass unix:/var/www/asmbb/engine.sock;
        include fastcgi_params;
    }

    location /images/ {
        expires 30d;
    }

    location /templates/ {
        expires 7d;
    }
}

逐项说明：fastcgi_pass unix:/var/www/asmbb/engine.sock 对接 4.3 中引擎自建的套接字（官方 VPS 章节原样）；include fastcgi_params 传递 SCRIPT_NAME 等 CGI 环境变量，缺了它引擎收不到合法请求；两个静态 location 让图片与模板由 Nginx 直接吐给浏览器、不占引擎线程。

启用并重载：

root@forum:~# ln -sf /etc/nginx/sites-available/asmbb /etc/nginx/sites-enabled/asmbb
root@forum:~# rm -f /etc/nginx/sites-enabled/default
root@forum:~# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
root@forum:~# systemctl reload nginx

4.5 验证站点响应

root@forum:~# curl -s -o /dev/null -w "http %{http_code} %{time_total}s\n" http://127.0.0.1/
http 200 0.002300s
root@forum:~# curl -sI http://127.0.0.1/
HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Mon, 02 Nov 2026 00:59:15 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive

2 毫秒级整页响应即 AsmBB 的核心卖点。若此处返回 502，说明引擎没起来，对照 8.2 处理。

4.6 初始化论坛（setup 模式）

全新安装首次访问时，引擎自动创建空 board.sqlite 并进入 setup 模式，页面标题为：

root@forum:~# curl -s http://127.0.0.1/ | grep -o '<title>[^<]*</title>'
<title>AsmBB: Create the admin account!</title>

在浏览器打开站点，提交管理员创建表单（等价于 POST /!adminrulez）。本实验创建的管理员：用户名 admin、密码 q1w2e3r4、邮箱 root@quzuo.net。回显：

root@forum:~# curl -s -o /dev/null -w "setup HTTP %{http_code}\n" -d "username=admin&email=root@quzuo.net&password=q1w2e3r4&password2=q1w2e3r4" http://127.0.0.1/!adminrulez
setup HTTP 302
root@forum:~# curl -s -o /dev/null -w "login HTTP %{http_code}\n" http://127.0.0.1/!login
login HTTP 302

管理员创建后论坛进入正常模式，随后在 !settings 管理页设置论坛标题、主机名（host）与 SMTP 参数（端到端组合配置实录见《AsmBB+Nginx+Postfix 组合实战指南》）。发一个主题验证写路径：

root@forum:~# curl -s -D - -o /dev/null -d "caption=Hello AsmBB on Ubuntu 22.04&source=[b]Hello[/b] AsmBB&tags=" http://127.0.0.1/!newthread
HTTP/1.1 302 Found
Location: /hello-asmbb-on-ubuntu-22-04.1/#1

主题 URL /hello-asmbb-on-ubuntu-22-04.1/#1 表明 slug 规则为「标题转写.主题ID」。

五、方案B：Lighttpd spawn 派生部署（备用方案）

官方 install.txt 通用路径之一：Lighttpd 通过 mod_fastcgi 的 bin-path 按需派生引擎进程（引擎检测到 stdin 是套接字时不再自建 engine.sock）。适合已有 Lighttpd 或不想引入 systemd 单元的场景。

5.1 安装 Lighttpd

root@forum:~# apt-get install -y lighttpd
Setting up libperl5.34:amd64 (5.34.0-3ubuntu1.9) ...
Setting up perl (5.34.0-3ubuntu1.9) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
root@forum:~# lighttpd -v
lighttpd/1.4.63 (ssl) - a light and fast webserver

5.2 合并包内示例配置（排障实录一）

包内 lighttpd.conf 是完整示例而非增量片段，官方 install.txt 明确要求把它合并进 /etc/lighttpd/lighttpd.conf 与 /etc/lighttpd/conf-enabled/。直接照抄进 conf-enabled/90-asmbb.conf 会撞车：

root@forum:~# lighttpd -t -f /etc/lighttpd/lighttpd.conf
Duplicate config variable in conditional 0 global: server.port
2026-11-02 00:25:16: (configfile.c.2158) source: /etc/lighttpd/conf-enabled/90-asmbb.conf line: 2 pos: 12 parser failed somehow near here: (EOL)
2026-11-02 00:25:16: (configfile.c.2158) source: /etc/lighttpd/lighttpd.conf line: 51 pos: 15 parser failed somehow near here: (EOL)

定位：示例第 2 行的 server.port、第 1 行的 server.document-root 与主配置 /etc/lighttpd/lighttpd.conf 已有定义重复。解决：主配置只改值、增量文件只留模块与 fastcgi 定义。主配置修改后关键行：

root@forum:~# grep -n -E 'server.(document-root|port)' /etc/lighttpd/lighttpd.conf
8:server.document-root        = "/var/www/asmbb"
14:server.port                = 8081
46:include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port

（8081 避开主方案 Nginx 的 80；独立部署时用默认 80 即可。）

5.3 补充 mod_fastcgi（排障实录二）

只改端口后语法通过，但访问返回 403——Lighttpd 还没把请求交给引擎：

root@forum:~# curl -s -o /dev/null -w "lighttpd HTTP %{http_code} size %{size_download}\n" http://127.0.0.1:8081/
lighttpd HTTP 403 size 341

403 Forbidden：目录无索引文件且未接 FastCGI。而直接往 90-asmbb.conf 写 fastcgi.server 又报 unknown config-key——模块没加载。最终 /etc/lighttpd/conf-enabled/90-asmbb.conf 内容：

server.modules += ( "mod_fastcgi" )
fastcgi.server = ( "/" =>
  ( "asmbb" =>
    (
      "socket" => "/tmp/asmbb-fcgi.socket",
      "bin-path" => "/var/www/asmbb/engine",
      "check-local" => "disable",
      "max-procs" => 1,
      "bin-options" => ( "copy-environment" => "false", "enter-directory" => "/var/www/asmbb" )
    )
  )
)

逐项说明：bin-path 让 Lighttpd 派生引擎（spawn 模式）；enter-directory 必须为站点目录，原因同 4.3 的 WorkingDirectory（相对 PT_INTERP）；check-local => disable 关闭本地路径探测，使所有 URI 都走 FastCGI。校验并重载：

root@forum:~# lighttpd -t -f /etc/lighttpd/lighttpd.conf
Syntax OK
2026-11-02 00:26:23: (configfile.c.426) Warning: mod_auth should be listed in server.modules before dynamic backends such as mod_fastcgi
root@forum:~# systemctl is-active lighttpd
active

5.4 验证

root@forum:~# curl -s -o /dev/null -w "lighttpd HTTP %{http_code} size %{size_download}\n" http://127.0.0.1:8081/
lighttpd HTTP 200 size 24151
root@forum:~# curl -s http://127.0.0.1:8081/ | grep -o '<title>[^<]*</title>'
<title>AsmBB: Threads list /</title>
root@forum:~# ps -eo pid,ppid,user,cmd | grep [e]ngine
www-data    3214       1  0 00:15 ?        00:00:00 /var/www/asmbb/engine
www-data    3887    3880  0 00:26 ?        00:00:00 /var/www/asmbb/engine

ps 出现两个 engine：3214 是方案A 的 systemd 常驻进程（PPID=1），3887 是 Lighttpd（PPID 3880）派生的 spawn 实例——两方案可共存，各自使用独立套接字（engine.sock 与 /tmp/asmbb-fcgi.socket）。

六、方案对比与选择建议

维度	方案A Nginx+systemd	方案B Lighttpd spawn
引擎启动方式	systemd 常驻，自监听 `engine.sock`	Lighttpd 按 `bin-path` 派生，套接字 `/tmp/asmbb-fcgi.socket`
进程模型	单进程多线程（上限 20 线程）	每 `max-procs` 一个进程
配置复杂度	systemd 单元 + Nginx server 块	仅 Lighttpd 两处配置
崩溃自愈	`Restart=on-failure` 自动拉起	Lighttpd 自动重新派生
官方定位	install.txt「VPS」章节，生产推荐	install.txt 通用章节
适用	生产 VPS、需要 TLS/反代生态	轻量单机、已有 Lighttpd

建议：生产环境选方案A（官方推荐路径、进程边界清晰、与组合实战篇的 TLS/Postfix 链路一致）；快速试用或资源极小的单机可选方案B。

七、配置说明

站点目录文件清单：引擎必需的只有 engine、ld-musl-i386.so、libsqlite3.so、templates/、images/ 五项；.htaccess（Apache 用）、lighttpd.conf（示例）、install.txt、License.txt、manifest.uuid 为非必需文件，官方允许删除，但建议保留 manifest.uuid 作版本指纹。
权限模型：www-data 对站点目录整目录可写（数据库、锁文件、套接字都在原地创建），可执行文件 755。
运行期生成物：board.sqlite（+-shm/-wal）、engine.sock、asmbb_ipc.lock、asmbb_queue.lock。锁文件为 0 字节属正常。
首次运行 = setup 模式：库中无用户时引擎强制显示管理员创建页；创建前论坛不可用，这是设计行为。

八、常见问题

8.1 手动启动引擎报「No such file or directory」，但文件明明存在

root@forum:~# cd / && /var/www/asmbb/engine
bash: line 1: /var/www/asmbb/engine: No such file or directory
exit=127

定位：报错的不是 engine 本身，而是其相对路径解释器 ./ld-musl-i386.so 不在当前目录。解决：必须先 cd /var/www/asmbb 再启动；systemd 单元用 WorkingDirectory= 保证这一点。这是 AsmBB 第一大坑。

8.2 浏览器/探针返回 502 Bad Gateway

引擎进程未运行（或套接字路径与 Nginx 配置不符）时 Nginx 即报 502——官方 install.txt 在 Finalizing 一节预告了这个现象。验证与恢复：

root@forum:~# systemctl stop asmbb
root@forum:~# curl -s -o /dev/null -w "stop后 HTTP %{http_code}\n" http://127.0.0.1/
stop后 HTTP 502
root@forum:~# systemctl start asmbb
root@forum:~# curl -s -o /dev/null -w "start后 HTTP %{http_code}\n" http://127.0.0.1/
start后 HTTP 200

8.3 直接改 `board.sqlite` 里的参数不生效

Params 表内容在引擎启动时缓存，直改库后必须 systemctl restart asmbb 才生效（实录见《AsmBB 日常运维手册》 7.4）。改参数优先走 !settings 管理页。

8.4 Lighttpd 报 Duplicate config variable / unknown config-key fastcgi.server

见五、5.2 与 5.3 排障实录：前者是示例配置与主配置重复定义，后者是漏加载 mod_fastcgi 模块。

九、卸载与清理

root@forum:~# systemctl disable --now asmbb
root@forum:~# rm -f /etc/systemd/system/asmbb.service && systemctl daemon-reload
root@forum:~# rm -rf /var/www/asmbb          # 站点目录含数据库 board.sqlite，删除前务必备份
root@forum:~# rm -f /etc/nginx/sites-enabled/asmbb /etc/nginx/sites-available/asmbb && systemctl reload nginx
root@forum:~# rm -f /etc/lighttpd/conf-enabled/90-asmbb.conf && systemctl reload lighttpd
root@forum:~# apt-get purge -y lighttpd nginx

下载目录清理实测回显：

root@forum:~# rm -rf /root/dl
root@forum:~# ls /root/
root@forum:~#

⚠️ 注意：/var/www/asmbb 删除即删除全部论坛数据。卸载前先按《AsmBB 日常运维手册》做 sqlite3 .backup 备份。

十、参考链接

官方安装文档（二进制包内 install.txt）：https://asm32.info/fossil/repo/asmbb/doc/trunk/install.txt
官方 VPS 安装帖：https://board.asm32.info/how-to-install-asmbb-on-vps-with-nginx-and-systemd.163/
v3.0 发布公告：https://board.asm32.info/asmbb-v3-0-has-been-released.401/
Fossil 主仓库：https://asm32.info/fossil/asmbb/
GitHub 只读仓库：https://github.com/johnfound/asmbb
站内相关：《AsmBB 介绍与选型指南》第二章（实体与技术栈澄清）

Ubuntu 22.04 安装 AsmBB v3.0 指南

Ubuntu 22.04 安装 AsmBB v3.0 指南

一、环境信息

二、前置条件

三、版本选型说明

四、方案A：Nginx + systemd 常驻部署（官方 VPS 推荐）

4.1 下载并校验官方二进制包

4.2 解压并部署到站点目录

4.3 配置 systemd 托管引擎

4.4 配置 Nginx FastCGI 转发

4.5 验证站点响应

4.6 初始化论坛（setup 模式）

五、方案B：Lighttpd spawn 派生部署（备用方案）

5.1 安装 Lighttpd

5.2 合并包内示例配置（排障实录一）

5.3 补充 mod_fastcgi（排障实录二）

5.4 验证

六、方案对比与选择建议

七、配置说明

八、常见问题

8.1 手动启动引擎报「No such file or directory」，但文件明明存在

8.2 浏览器/探针返回 502 Bad Gateway

8.3 直接改 board.sqlite 里的参数不生效

8.4 Lighttpd 报 Duplicate config variable / unknown config-key fastcgi.server

九、卸载与清理

十、参考链接

8.3 直接改 `board.sqlite` 里的参数不生效