在鲲鹏 ARM 架构的服务器上跑麒麟 V10，业务侧要把密码存储从 SHA-256 加盐换成 Argon2，这件事听起来像一条apt install就能解决，真上手才发现发行版软件源里根本没有可用的包，或者版本老到连argon2id都不支持。我前后在三套不同的鲲鹏机器上折腾过这个组合，从 configure 报错到libargon2.so.1: cannot open shared object file，该踩的坑基本都踩了一遍。这篇就把在鲲鹏 ARM 架构 + 麒麟 V10 环境下安装 Argon2 的完整路径摊开讲：包括为什么值得用源码编译、configure 参数怎么根据 ARM 平台调整、装完之后各语言绑定怎么接、运行期动态库找不到怎么排，以及成本参数在这类机器上到底该设成多少。无论你是第一次接触密码哈希库的后端开发，还是需要在一批 ARM 服务器上做统一部署的运维，下面的步骤都可以直接照着执行。

1. 先想清楚：为什么在 ARM 服务器上装 Argon2 要单独写一篇

很多人第一反应是"装个库而已"，但在 ARM64 + 麒麟 V10 这个组合里，安装路径的选择会直接影响后面几个月的运维成本。这一步想不清楚，后面会反复返工。

1.1 Argon2 到底解决的是哪一类问题

Argon2 是密码哈希竞赛的胜出算法，现在被 OWASP 密码存储备忘单列为首选。它和传统 SHA 系列的根本区别在于三点：内存硬（memory-hard）、可调并行度、内置盐与参数编码。传统做法sha256(salt + password)可以用 GPU 或专用硬件每秒尝试上亿次，因为计算过程几乎不占内存；Argon2 强制每次计算吃掉几十 MB 内存，攻击者想并行就得堆同样规模的内存，成本曲线陡增。

Argon2 有三个变体：Argon2d、Argon2i、Argon2id。d依赖数据决定内存访问顺序，抗 GPU 最强但存在侧信道风险；i用固定模式访问内存，抗侧信道但抗 GPU 稍弱；id是混合模式，前若干轮用i的方式，后面用d的方式。新系统一律选argon2id，没有例外。

真正让人关心的是参数。Argon2 有三个核心成本参数：t（迭代次数）、m（内存用量，单位 KiB）、p（并行度/通道数）。这三个数共同决定了单次哈希的耗时。在一台 x86 笔记本上合适的参数，搬到鲲鹏机器上耗时可能翻倍或腰斩，必须重新测。这也是为什么后面第 4 节要花一整节讲实测。

1.2 麒麟 V10 加 ARM64 带来的三个现实约束

第一个约束是软件源里大概率没有现成的 libargon2 包。即使有，版本也可能停在很老的分支，只导出argon2i_hash_raw而不带argon2id相关接口，或者argon2_encodedlen这类辅助函数缺失，导致业务代码编译不过。我遇到过最尴尬的情况是开发机（x86）上apt install libargon2-dev一条命令搞定，代码写完推到鲲鹏测试机，pkg-config --exists libargon2直接返回非零。

第二个约束是工具链版本偏保守。麒麟 V10 各小版本自带的 gcc 从 7.x 到 9.x 不等，autotools 版本也不算新。Argon2 的上游构建脚本用了configure.ac里的现代宏，如果本地 autoconf 太老，从 Git 仓库克隆下来直接./autogen.sh可能报出一堆宏未定义的错误——这种情况下必须用官方发布的 tarball，因为里面已经带了 configure 脚本，不需要重新生成。

第三个约束是动态库搜索路径的默认值。ARM64 上/usr/local/lib不一定在/etc/ld.so.conf.d/的覆盖范围内，装完库之后编译通过、运行报找不到.so是最常见的一类问题。麒麟 V10 在这方面和常规 Linux 发行版行为一致，但默认配置更保守，必须手动加一条 conf 文件。

把这三个约束摆出来，安装路线其实就只剩一条比较稳的路了。

1.3 三条安装路线的取舍

我把能想到的三条路列出来对比一下，方便你按自己的环境选：

我的建议是：服务器上装动态库，容器镜像里编静态库。生产服务器通常有多套业务共用同一台机器，动态库能减少重复体积，也方便统一打安全补丁；而容器镜像追求的是"拷进去就能跑"，静态链接省掉了运行期找库的麻烦，尤其是基础镜像裁剪得只剩 glibc 的情况。

至于"用 Python/Go 的纯语言实现绕开系统库"这条路，后面第 5 节会单独说，它在某些场景下反而更省事，但不适合所有语言。

2. 动手前的环境摸底：这几条命令别省

我在一台新机器上动手之前，固定会先跑一遍摸底，把架构、系统版本、编译器、已有库全部确认清楚。跳过这一步的代价是后面每遇到一个报错都要重新猜环境。

2.1 确认架构、发行版与 C 库版本

第一条命令永远是uname -m。在鲲鹏机器上应该返回aarch64。如果返回armv7l那说明是 32 位 ARM，Argon2 依然能编，但内存上限会受地址空间限制，m参数不能设太大。如果返回x86_64，说明你连错机器了——这种情况比我预想的多，尤其是跳板机同名的时候。

接着确认系统版本：

cat /etc/os-release uname -r getconf GNU_LIBC_VERSION ldd --version | head -n 1

/etc/os-release里能看到VERSION_ID和PRETTY_NAME，确认是 V10 的哪个小版本。getconf GNU_LIBC_VERSION输出类似glibc 2.28这样的结果，这个数字很关键：Argon2 本身对 glibc 版本要求不高（2.17 以上基本没问题），但你后面要装的 Python 绑定、PHP 扩展可能对 glibc 有硬性要求。

还有一个容易被忽略的点是内核页大小。ARM64 支持 4K、16K、64K 三种页大小，麒麟 V10 默认一般是 4K，但某些为特定场景定制的镜像可能用 64K。页大小会影响大块内存分配的效率，间接影响 Argon2 在高m值下的实际吞吐：

getconf PAGESIZE

如果输出 65536，说明是 64K 页。这个信息本身不用改配置，但后面做性能压测时要知道，它会让内存分配行为和常规 4K 页机器有差别。

2.2 检查编译工具链是否齐全

Argon2 的构建依赖 gcc、make、autotools（如果用 tarball 则只需要 make）。检查方式：

gcc --version make --version pkg-config --version

三条命令任意一条返回"command not found"，就先把开发工具装齐。麒麟 V10 上一般是：

sudo yum groupinstall "Development Tools" -y # 或按需单独装 sudo yum install -y gcc gcc-c++ make pkgconfig

这里有个细节值得说：一定要装pkgconfig（注意有的源里包名是pkg-config）。Argon2 的make install会往$(PREFIX)/lib/pkgconfig里写一个libargon2.pc文件，后面你用pkg-config --cflags --libs libargon2拿到正确的编译参数。没装 pkg-config，这个便利就没了，只能手写-I和-L，很容易漏。

顺便确认一下autoconf和automake的版本，虽然用 tarball 不需要它们，但如果你要从 Git 仓库取代码就必须有：

autoconf --version | head -n 1 automake --version | head -n 1

2.3 先确认本地源里到底有没有现成的包

在动手编译之前，值得花三十秒确认一下有没有现成的：

yum search argon2 yum info libargon2 2>/dev/null rpm -qa | grep -i argon find / -name "libargon2*" 2>/dev/null

情况通常分三种。第一种，什么都没有，那就老老实实编译。第二种，有libargon2但没有-devel包，意味着只有运行库没有头文件，还是得自己编头文件和.pc文件，不如直接编完整包。第三种，有包但版本很老，这时候用pkg-config --modversion libargon2看版本号，如果低于 20171227，考虑argon2id支持是否完整——argon2id是在 20161029 之后才加入的，太老的版本只有argon2i和argon2d。

还有一种特殊情形：机器上已经有别的软件静态链接了 argon2，留下了一个libargon2.a但没有.so。这时候直接编译会有符号冲突风险，建议用独立前缀安装，比如/opt/argon2，彻底不碰系统路径。

3. 源码编译 Argon2 的完整过程

这一节是核心，我把每一步的命令、参数含义和可能出的状况都写清楚。照抄可行，但建议边看边理解为什么这么写。

3.1 拿到源码包并校验完整性

上游仓库的发布 tarball 命名规则是phc-winner-argon2-<版本号>.tar.gz，写这篇文章时主线最新的稳定 tag 是20190702。生产环境建议用固定的 tag 或 tarball，不要直接用 master 分支的 zip，因为 master 上的configure脚本可能没生成，必须自己跑autogen.sh，而autogen.sh对 autoconf 版本有要求。

内网离线环境的常规做法是：在能上网的机器上下载，算出哈希，挪进去再比对。

# 有外网的机器上 curl -L -O https://github.com/P-H-C/phc-winner-argon2/archive/refs/tags/20190702.tar.gz sha256sum 20190702.tar.gz

把哈希值抄下来。到内网机器上：

sha256sum 20190702.tar.gz # 与上面记录的值逐字符比对 tar -xzf 20190702.tar.gz cd phc-winner-argon2-20190702/ ls

ls之后应该能看到Makefile、configure、src/、include/、libargon2.pc.in这些文件。如果没看到configure，只有configure.ac，说明你拿的是 Git 快照而不是发布包，需要先./autogen.sh，而这一步在麒麟 V10 上很可能因为 automake 版本不够而失败。遇到这种情况，退回去找带configure的 tarball。

提示：在解压后的目录里先看一眼CHANGELOG.md的最后几条，确认这个版本有没有已知的构建问题。有些版本在特定平台上需要打小补丁。

3.2 configure 参数的选法与背后逻辑

进入目录后，先别急着./configure。Argon2 的 configure 支持的参数不多，但每一个都有实际影响。

./configure \ --prefix=/usr/local \ --enable-static \ --disable-shared \ --build=aarch64-unknown-linux-gnu

先解释每个参数：

--prefix=/usr/local是安装前缀。选择/usr/local而不是/usr的原因是不覆盖系统包管理器管理的路径。如果哪天系统源更新了 argon2 相关的包，装到/usr下会产生文件归属冲突，rpm -V校验一片报错，排查起来非常麻烦。装到/usr/local就完全隔离，出问题删目录就行。

--enable-static和--disable-shared这个组合意味着只生成静态库libargon2.a。如果你只做服务器部署，建议反过来：--enable-shared --disable-static，因为动态库体积小、多进程共享内存页、打补丁不用重编业务代码。我上面写静态是为了演示容器场景。默认情况下 configure 两个都开，如果你想省事，什么参数都不加直接跑也行，生成.a和.so两套。

--build=aarch64-unknown-linux-gnu是显式声明构建平台。在原生编译（在 ARM 上编 ARM）的场景下，autotools 通常能自动识别，加不加都行；但如果你以后要做交叉编译，这个参数就必须准确，否则 config.guess 可能识别成错误的架构，生成一堆只在错误平台下有效的汇编。原生编译时加上的好处是日志更清晰，出问题时能一眼看出平台判断对不对。

还有两个参数虽然不常用，但值得知道：

• --libdir=/usr/local/lib64：麒麟 V10 有些配置会默认把 64 位库放到lib64而不是lib，如果make install后发现库跑到了意料之外的目录，用这个参数强制指定。
• CFLAGS环境变量：可以传-O2或-O3。默认Makefile里已经带了-O3，一般不用改。但如果你的麒麟 V10 上 gcc 版本偏老，-O3在 ARM 上可能触发激进优化导致测试失败，这时候退到-O2更稳：

CFLAGS="-O2 -fPIC" ./configure --prefix=/usr/local --enable-shared

-fPIC在编共享库时是必须的，上游 Makefile 已经处理，但如果你自己改 build 脚本要记得。

执行 configure 时留意输出末尾的摘要，重点看两行：checking for gcc...后面是不是正确的编译器路径，checking whether the C compiler works...是不是yes。如果后者是no，通常是工具链缺glibc-devel或者 gcc 装得不完整。

3.3 编译、安装与动态库缓存刷新

configure 通过后，编译和安装就很快了，Argon2 代码量不大，在鲲鹏机器上一般几十秒能编完。

make -j$(nproc) sudo make install

-j$(nproc)让 make 用满所有核心。鲲鹏机器核心数通常不少，这个参数能把编译时间压下来。编完之后建议先跑一下自带的测试：

make test

这个目标会跑kats/目录下的一套已知答案测试，用固定的输入输出比对实现是否符合规范。这一步千万别跳过，它能在三十秒内告诉你这个版本在你的编译器和优化级别下有没有产生计算结果偏差——如果make test就不过，后面接业务代码只会得到一堆校验失败，排查方向会完全跑偏。

安装完成后确认文件落位：

ls -l /usr/local/lib/libargon2* ls -l /usr/local/include/argon2.h ls -l /usr/local/lib/pkgconfig/libargon2.pc

正常应该看到libargon2.so -> libargon2.so.1、libargon2.so.1.0.0这类的软链结构（如果你开了共享库），以及头文件和 pc 文件三件套。

接下来是最关键的一步，刷新动态链接器的缓存：

echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/argon2.conf sudo ldconfig ldconfig -p | grep argon2

最后一条命令应该输出类似libargon2.so.1 (libc6,AArch64) => /usr/local/lib/libargon2.so.1的内容。注意括号里应该是AArch64，如果显示的是x86-64，说明ld.so.conf里混进了错误路径，或者机器上残留了别的架构的库，必须清理掉，否则运行时会加载错架构的.so直接段错误。

注意：ldconfig刷完不会立刻对已启动的进程生效。如果你的业务服务是常驻进程，改完库路径要重启服务，否则它仍然引用旧的映射。

3.4 写一个最小验证程序确认能编能跑

装完之后别急着接业务，先用一个十几行的 C 程序验证一遍完整链路：头文件能找到、链接能找到、运行时能找到库、计算结果符合预期。

#include <argon2.h> #include <stdio.h> #include <string.h> #include <stdlib.h> int main(void) { /* 注意：这里的盐仅为验证用途，生产环境必须用随机数生成器 */ unsigned char salt[16] = {0}; unsigned char hash1[32]; unsigned char hash2[32]; char encoded[256]; for (int i = 0; i < 16; i++) salt[i] = (unsigned char)(i + 1); const char *pwd = "a-sample-password"; uint32_t t_cost = 3; uint32_t m_cost = 65536; /* 单位 KiB，即 64 MiB */ uint32_t parallelism = 4; int rc = argon2id_hash_raw(t_cost, m_cost, parallelism, pwd, strlen(pwd), salt, sizeof(salt), hash1, sizeof(hash1)); if (rc != ARGON2_OK) { printf("hash failed: %s\n", argon2_error_message(rc)); return 1; } /* 再算一次，确认同一组参数结果稳定 */ argon2id_hash_raw(t_cost, m_cost, parallelism, pwd, strlen(pwd), salt, sizeof(salt), hash2, sizeof(hash2)); printf("deterministic: %s\n", memcmp(hash1, hash2, sizeof(hash1)) == 0 ? "yes" : "no"); /* 生成带参数的编码串，这才是应该存库的东西 */ size_t enc_len = argon2_encodedlen(t_cost, m_cost, parallelism, sizeof(salt), sizeof(hash1), Argon2_id); if (enc_len > sizeof(encoded)) { printf("buffer too small\n"); return 1; } rc = argon2id_hash_encoded(t_cost, m_cost, parallelism, pwd, strlen(pwd), salt, sizeof(salt), sizeof(hash1), encoded, enc_len); if (rc != ARGON2_OK) { printf("encode failed: %s\n", argon2_error_message(rc)); return 1; } printf("encoded: %s\n", encoded); return 0; }

编译有两种写法。装了 pkgconf 的情况下：

gcc verify.c -o verify $(pkg-config --cflags --libs libargon2)

如果pkg-config --exists libargon2返回非零，说明 pc 文件路径没在PKG_CONFIG_PATH里，手动指定：

gcc verify.c -o verify -I/usr/local/include -L/usr/local/lib -largon2

运行：

./verify ./verify

两次运行输出应该完全一致（因为盐是固定的）。输出里的encoded字段形如$argon2id$v=19$m=65536,t=3,p=4$...$...，这一段才是应该存进数据库的东西——它自带版本号、参数和盐，将来调参数的时候老密码还能用老参数校验，平滑迁移。很多人只存了裸哈希，导致参数一改全站密码失效，这个坑一定要避开。

4. Argon2 成本参数的实测与调优

库装好只是第一步。参数选错，要么安全强度不够，要么把服务器 CPU 和内存打满。这一节讲怎么在鲲鹏机器上定出合适的数值。

4.1 三个成本参数分别影响什么

t（时间成本）是迭代轮数，每增加一轮时间线性增加，内存占用不变。m（内存成本）是每次哈希占用的内存，单位 KiB，增加它同时提升攻击成本和防御强度，但对哈希耗时的影响是非线性的。p（并行度）是通道数，它决定了内部能用几个线程并行计算，注意p增大不必然加快单次哈希——libargon2 内部会按p开线程，但线程创建和同步本身有开销，在单次调用的场景下，p从 1 提到 4 可能只快 20%，而内存占用要到m × p的量级。

这里有个很多人理解错的地方：m是总内存，不是每通道内存。库内部会把m平均分给p个通道。所以设置m=65536, p=4表示总共 64 MiB，每通道 16 MiB。如果你按"64 MiB × 4 = 256 MiB"去估服务器容量，会低估攻击者成本，也会高估自己的内存压力——实际是 64 MiB。

OWASP 密码存储备忘单给出的几组参考配置，可以直接拿来对照：

这些只是起点。真正的原则是：在你目标机器上，单次哈希耗时落在 250 毫秒到 500 毫秒之间，同时内存占用不超过单次请求可分配的合理上限。低于 250 毫秒说明还有加强空间，高于 1 秒会明显拖慢登录接口。

4.2 在鲲鹏机器上跑实测拿数据

库自带了 bench 工具，能直接跑出一张参数扫描表。在源码目录里：

make bench ./argon2-bench -h

不过自带的 bench 参数组合是固定的，我更推荐自己写个小循环，按业务实际参数测：

#include <argon2.h> #include <stdio.h> #include <string.h> #include <time.h> static double bench_once(uint32_t t, uint32_t m, uint32_t p) { unsigned char salt[16] = {1}; unsigned char hash[32]; const char *pwd = "bench-password"; struct timespec a, b; clock_gettime(CLOCK_MONOTONIC, &a); argon2id_hash_raw(t, m, p, pwd, strlen(pwd), salt, 16, hash, 32); clock_gettime(CLOCK_MONOTONIC, &b); return (b.tv_sec - a.tv_sec) * 1000.0 + (b.tv_nsec - a.tv_nsec) / 1e6; } int main(void) { uint32_t ms[] = {12288, 19456, 32768, 47104, 65536, 131072}; uint32_t ps[] = {1, 2, 4, 8}; for (int i = 0; i < 6; i++) for (int j = 0; j < 4; j++) printf("m=%6u p=%u t=2 -> %7.1f ms\n", ms[i], ps[j], bench_once(2, ms[i], ps[j])); return 0; }

编一个跑一下，把数据抄成表格。在我手头那台 32 核鲲鹏机器上，m=65536, p=4, t=3大约是 320 毫秒，m=47104, p=1, t=1大约 95 毫秒。这些数字跟 CPU 主频、内存带宽强相关，不同型号的鲲鹏差距可能到 1.5 倍，所以必须以你自己机器的数据为准。

测的时候有几个纪律：

第一，清空缓存干扰。把测试程序跑三遍取中位数，第一遍往往受冷启动影响偏慢。

第二，用真实并发做压力测试。单次 320 毫秒听起来没问题，但如果登录接口 QPS 是 100，意味着同一时刻有 32 个哈希在跑，每个吃 64 MiB，总内存 2 GB。这个数字必须提前算出来，否则上线后 OOM 就是必然。

第三，注意p和 CPU 核数的关系。p设成 8 时，库内部会开 8 个线程，如果容器限制了 CPU 配额只有 2 核，线程会互相抢占，实测反而变慢。

4.3 内存与并发的容量估算

把上面的数据落成一个估算公式：单机可承载的并发哈希数 ≈ 可用内存 / (m × 1.2)。乘 1.2 是给库内部临时缓冲和编码字符串留余量。

举个实际配置：一台 64 GB 内存、32 核的鲲鹏服务器，分配给应用的堆内存 16 GB，Argon2 参数选m=65536, p=4, t=3。那么理论并发上限是 16384 / 76.8 ≈ 213 个同时进行。但 CPU 侧 32 核在p=4时只能同时跑 8 个完整哈希，所以真正的瓶颈是 CPU 而不是内存——单次 320 毫秒摊到 8 路并行，吞吐约 25 次/秒。这个数字才是你登录接口的性能天花板。

如果这个吞吐不够，有三个方向：降参数（牺牲安全性换吞吐）、加机器、或者把 Argon2 放到异步队列里跑（登录请求先返回，后台校验完再回调，但这种做法会改变交互模型，慎用）。我一般选降t到 2 并把m保持在 46 MiB 以上，在安全性和吞吐之间取平衡点。

还有个小技巧：登录失败和登录成功的路径不要在同一个线程池里排队。Argon2 校验对一个不存在的用户也应该跑一遍完整的哈希（否则可以通过响应时间判断用户是否存在，这是典型的时序侧信道），但可以跑一个m固定、参数更低的"假哈希"，成本降一个量级。

5. 各语言绑定怎么接上这套库

系统库里装好了，业务代码还得接。不同语言接法差别很大，有些能直接用系统库，有些会自己编一份，理解清楚能避免"装了但没用上"的困惑。

5.1 C/C++ 项目直接链接

最直接的情况。项目用 CMake 的话：

find_package(PkgConfig REQUIRED) pkg_check_modules(ARGON2 REQUIRED libargon2) target_include_directories(your_target PRIVATE ${ARGON2_INCLUDE_DIRS}) target_link_directories(your_target PRIVATE ${ARGON2_LIBRARY_DIRS}) target_link_libraries(your_target PRIVATE ${ARGON2_LIBRARIES})

如果pkg_check_modules报找不到，检查是不是PKG_CONFIG_PATH没包含/usr/local/lib/pkgconfig。可以在 CMakeLists 开头临时加一句：

set(ENV{PKG_CONFIG_PATH} "/usr/local/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")

不用 pkg-config 的裸 Makefile 项目，链接参数就是：

CFLAGS += -I/usr/local/include LDFLAGS += -L/usr/local/lib -largon2

注意-largon2要放在源文件之后，GNU ld 的符号解析是从左到右的，顺序反了会报 undefined reference。这个错误我在新手代码里见过很多次。

5.2 Go 项目：先想清楚要不要用 cgo

Go 侧有个关键选择：用golang.org/x/crypto/argon2这个纯 Go 实现，还是用 cgo 包系统的 C 库。

纯 Go 实现的优势很明显：没有 cgo，交叉编译无障碍，Docker 多阶段构建可以完全静态，在 ARM64 上编译 ARM64 更是零配置。代价是性能。纯 Go 版本没有用到 NEON 指令，也不做 x86 那套 SIMD 优化，在鲲鹏机器上实测大约比 C 版本慢 15% 到 30%。对登录接口这种场景，这个差距完全可以接受。

package main import ( "encoding/hex" "fmt" "golang.org/x/crypto/argon2" ) func main() { salt := []byte("0123456789abcdef") key := argon2.IDKey([]byte("a-sample-password"), salt, 3, // time 64*1024, // memory, 单位 KiB 4, // threads 32, // keyLen ) fmt.Println(hex.EncodeToString(key)) }

注意argon2.IDKey里的memory参数单位是 KiB，time是迭代次数，threads是并行度。这三个参数和 C API 的t/m/p一一对应，但顺序不同，从 C 代码迁过来的时候特别容易写反，写反的后果是哈希强度差几十倍，而且不会有任何报错。

如果确实要用 cgo 接系统库，编译时要把路径传进去：

CGO_ENABLED=1 \ CGO_CFLAGS="-I/usr/local/include" \ CGO_LDFLAGS="-L/usr/local/lib -largon2" \ go build -o app .

这里有个 ARM 上特别容易踩的坑：cgo 会把$CGO_LDFLAGS里的路径写进二进制的 RPATH，但不一定包含运行时搜索路径。也就是说编译能过，跑到目标机器上照样报libargon2.so.1 not found。稳妥的做法还是把ld.so.conf配好，不要依赖 cgo 的 RPATH。

5.3 Python、PHP、Java 的接入要点

Python 侧推荐argon2-cffi。有意思的是，这个包在 pip 安装时会把 libargon2 的 C 源码一起编进去，不依赖系统里装的库。所以在鲲鹏 + 麒麟 V10 上装它，实际上是在编一份独立的静态副本：

pip install argon2-cffi

前提是机器上有 gcc 和 Python 开发头文件（python3-devel）。如果装的时候报错找不到Python.h，就是缺 devel 包。装完之后：

from argon2 import PasswordHasher from argon2.exceptions import VerifyMismatchError ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4, hash_len=32, salt_len=16) h = ph.hash("a-sample-password") print(h) try: ph.verify(h, "a-sample-password") print("match") except VerifyMismatchError: print("mismatch")

PasswordHasher会自己生成随机盐并把参数编码进字符串，这是最省心的用法。需要提醒的是：ph.verify()在参数不匹配时抛的是InvalidHashError的子类而不是VerifyMismatchError，业务代码里捕获要写全，否则用户改密码后旧记录校验会直接 500。

PHP 侧，从 7.4 起password_hash原生支持PASSWORD_ARGON2ID，但要求编译 PHP 时带了--with-password-argon2。在麒麟 V10 上用系统包管理器装的 PHP 未必开了这个选项，判断方式：

<?php var_dump(in_array('argon2id', password_algos()));

返回 false 的话，要么重编 PHP 加参数，要么走 PECL 的sodium扩展用sodium_crypto_pwhash_str。我一般建议后者，改动小。

Java 侧最省事的是 BouncyCastle 的纯 Java 实现，Argon2BytesGenerator不需要任何本地库，跨架构无差异，只是性能比 C 版本低一些。在 ARM 服务器上跑 JVM 本身就有开销，这点差距可以忽略。

6. 常见问题与排查速查表

这一节是我这几年攒下来的报错清单，按出现频率排序。遇到问题先来这里对号入座，能省掉大量搜索时间。

6.1 编译期问题

configure: error: C compiler cannot create executables：这是最基础的错误，通常是 gcc 装了但缺glibc-devel或者binutils。查config.log末尾几行，里面会写明具体是哪个测试程序链接失败。九成的情况是缺 32 位兼容库或者缺gcc-c++。

undefined reference to 'pthread_create'：老版本 Makefile 漏了-lpthread。手动改 Makefile 在LIBS里加上，或者用LDFLAGS="-lpthread" ./configure。Argon2 内部用了线程池，这个依赖绕不开。

autoconf: command not found或possibly undefined macro: AC_...：说明你拿的是 Git 快照而不是发布 tarball。回去下带configure的版本，别硬扛。在麒麟 V10 上补齐 autotools 全家的版本兼容性很麻烦，不值得。

编译通过但make test失败：大概率是-O3在这个 gcc 版本 + ARM 平台组合下有行为差异。改成CFLAGS="-O2" ./configure ...重编一次，八成都好了。如果-O2还不行，检查是不是机器上有多份 argon2 头文件，include路径搜到了旧版本。

6.2 运行期问题

error while loading shared libraries: libargon2.so.1: cannot open shared object file：出现频率最高。三种解法按优先级：

1. 配ld.so.conf.d然后ldconfig（推荐，一劳永逸）。
2. 启动脚本里设LD_LIBRARY_PATH=/usr/local/lib（能用，但每个入口都要设，容易漏）。
3. 编译时加-Wl,-rpath,/usr/local/lib，把路径烧进二进制（适合容器）。

要注意libargon2.so.1里的1是 soname 的主版本号。ldconfig -p | grep argon2看到的是libargon2.so.1，但ls /usr/local/lib可能只有libargon2.so（开发用软链）和libargon2.so.1.0.0（实体文件），中间的libargon2.so.1软链如果被误删，运行时就会找不到。用ls -l看清楚软链结构。

程序启动即段错误（Segmentation fault）：ARM 上最常见的原因是加载了错误架构的库。ldconfig -p | grep argon2输出里括号应该是AArch64。如果显示x86-64，说明/usr/local/lib下混进了从 x86 机器拷过来的.so，删掉重装。

还有一种可能是版本不匹配：程序编译时用的头文件版本和运行时加载的.so版本不一致，结构体大小对不上，函数调用时栈被破坏。排查方法是对比pkg-config --modversion libargon2和strings /usr/local/lib/libargon2.so | grep -i version。

同一个密码校验时对时错：这是最让人头疼的一类。先确认三件事：盐是不是每次都用同一个（应该不同）、参数是不是完全一致（t/m/p任一不同结果就不同）、编码串里的版本号$v=是不是一致。如果盐和参数都没问题还出现偶发失败，检查是不是多线程共享了同一个argon2_context结构体——这个结构体不是线程安全的，必须每次调用重新构造。

6.3 排查速查表

把上面这些整理成一张表，方便贴在工作文档里：

注意：任何改动参数的操作都要考虑存量数据。已经用老参数存的哈希，必须能用老参数校验成功，否则用户全部无法登录。正确做法是存完整编码串，校验时从串里解析参数，新用户注册用新参数，老用户下次登录成功时顺手重算一遍升级。这个迁移策略要从第一天就设计进去。

7. 我在几套环境里攒下的一些体会

关于静态库和动态库的选择，我现在的默认答案是：物理机装动态，容器用静态。之前在一个容器镜像里用了动态库方案，基础镜像裁剪得比较厉害，ldconfig都没有，每次启动都要在 entrypoint 里手动设置环境变量，后来改成--enable-static重编，镜像里只留一个二进制，清爽很多，代价是二进制大了几百 KB，完全可以接受。

参数这件事，我给的建议是先测后定，别抄网上的数值。同一套m=65536, t=3, p=4，在 x86 上跑 180 毫秒，在一台主频偏低的鲲鹏上能跑到 500 毫秒以上。上线前一定要在目标硬件上跑一遍实测，把数据记进配置注释里，方便以后有人问"为什么是 3 不是 4"的时候有据可查。我们现在的做法是在配置里直接写一行注释标注实测耗时和机器型号，改了参数必须同步更新这行注释。

还有一点是文档里很少提的：装完之后记得把argon2.h和.pc文件的位置写进团队的开发环境说明里。我遇到过开发在本地 x86 上用包管理器装，头文件在/usr/include，代码里写了#include <argon2.h>一切正常，推到 ARM 测试环境编译时因为 include 路径不同直接失败，排查了半天。统一用pkg-config拿编译参数，这类问题基本能绝迹。

最后提一个容易被忽略的运维动作：给ld.so.conf.d加完 conf 文件之后，如果以后升级 argon2 到新版本，ldconfig要重新跑一遍。有些自动化脚本只做make install不做ldconfig，升级后可能出现新旧.so混用，症状是随机崩溃，非常难查。把ldconfig写进升级脚本的最后一行，这个习惯能省掉很多深夜排查。