这是三节点OpenStack Queens环境搭建系列的第三篇，前面控制节点的基础环境、MySQL数据库、消息队列这些底层服务已经就绪，这篇专门来解决keystone——OpenStack的身份认证服务。keystone就是整个系统的“前台”，谁要进云平台，先在这里验明正身；谁要调用哪个组件的接口，先在这里查看服务目录和endpoint。后续要装的glance、nova、neutron，没有一个能绕过它。这篇文章我会按自己实际部署过一遍的顺序来写，从数据库授权、软件包安装、核心配置、bootstrap初始化到Apache WSGI接管，再到最后的命令行验证和常见故障排查，尽量做到照着做就能跑通。适合刚接触OpenStack部署、想手动搭一套Queens环境而不是用一体化部署工具的读者。

1. keystone在整个OpenStack里的位置：为什么必须第一个装

1.1 keystone到底管着哪几件事

很多新手第一次听到keystone，以为只是一个“登录认证”的组件，其实它管的事情远不止这些。最核心的有三块：身份认证、token签发和服务目录管理。

身份认证比较好理解，就是验证“你是谁”。OpenStack里面用user（用户）、project（项目，早期也叫tenant租户）、role（角色）来描述权限关系。user要登录必须有一个project，并且在这个project里被授予了某种角色，比如admin、member。这种模式和我们上班进公司很像：门禁卡是你的user，你所属的部门可以理解成project，你在这个部门里的职位就是role，三者共同决定了你能进哪些门、能开哪间办公室。

token是认证通过后签发的一张“临时通行证”。客户端拿着它去访问nova、glance这些组件的API，组件不需要再问你的密码，而是拿着token去keystone校验是不是有效，以及这个token背后的人有没有权限。这就避免了每个组件都要保存一份用户密码，大大简化了服务间的信任关系。

服务目录就更关键了。OpenStack里每个服务都会注册自己的服务名称、类型和一组endpoint（包括public、internal、admin三种访问地址）。客户端在拿到token的同时，也能从keystone拿到这个目录，知道该去哪台机器、哪个端口调nova的API。可以说，keystone不仅是入口，还是整个云平台的地图。

1.2 Queens版本的keystone有什么变化

如果读者以前看过老教程，可能会发现步骤完全不同。这是因为到Queens版本，keystone的部署方式已经发生了几个重要变化。

首先，token格式从原来的UUID、PKI变成了Fernet。Fernet是一种对称加密的token，它不存数据库，而是把用户信息、权限信息和过期时间直接加密到token字符串里。这样做的好处显而易见：keystone节点无状态了，做高可用时不需要同步token数据库，只要保证所有控制节点的Fernet密钥一致就行。但也带来一个要求，就是必须用keystone-manage fernet_setup生成密钥，密钥文件一旦丢失，所有已有token全部失效。

其次，API版本全面转向v3，老版本的v2.0接口在Queens里已经处于被废弃状态，官方文档也不再推荐使用。v3最大的改变是引入了domain（域）的概念，默认有一个名为Default的域，管理员在创建用户和项目时通常都要显式指定--domain default，否则keystone会按默认域去处理。这导致了很多环境变量里多了OS_PROJECT_DOMAIN_NAME和OS_USER_DOMAIN_NAME，很多人第一次跑命令报“认证失败”就是因为漏配了这两个参数。

还有就是初始化方式。旧版本要先通过环境变量里的OS_SERVICE_TOKEN和OS_SERVICE_ENDPOINT，手动创建admin用户、admin项目、admin角色，然后还要手动绑定关系。Queens推荐用keystone-manage bootstrap一条命令完成这些初始工作，省去了一堆重复操作，出错的概率也小很多。

1.3 和后续组件的协作关系

装完keystone之后，后面每一个服务，比如glance、nova、neutron，都会经历这样一个过程：先在keystone里创建专门的service账号（比如glance用户），把这个账号放到service项目下，赋予admin角色；然后向keystone注册自己的服务类型和endpoint；再配置自己的配置文件，告诉它“认证请找controller的5000端口，我的service账号密码是xxx”。应用起来之后，组件之间互相调用时，也都会使用keystone签发的token。

所以一个keystone安装是否成功，评判标准不只是“web服务能访问”、“登录能通过”，还要看service实体、endpoint、项目角色这些数据是否齐全。而且，如果你一开始keystone的配置有偏差，比如admin密码写错、endpoint地址用了无法解析的hostname，后面排查会是连环问题。这也是为什么我一直建议先单独把keystone验证得干干净净，再继续装下一个组件。

2. 动手前的准备：数据库、缓存、软件包一个都不能少

2.1 控制节点基础环境自查

在安装keystone之前，先确认控制节点的基础环境没有历史包袱。系统层面，我用的是CentOS 7.x，配合Queens版本的OpenStack源。如果你用Ubuntu 16.04，包名略有差异，但思路一致。要求能正常访问外网（至少能访问配置好的OpenStack yum源），/etc/hosts里已经写好了controller这个主机名对应的IP，并且节点之间可以通过主机名互访。

几个容易踩坑的基础项：

• 关闭防火墙，或者至少放行5000端口。部署调试阶段直接systemctl stop firewalld能省很多时间。
• 确认SELinux没有强制拦截。如果不想彻底关闭，后面需要为httpd和keystone设置对应的布尔规则，这个在问题章节细说。
• 时间同步一定要保证。token是有时效性的，控制器时间偏差超过一定范围，token校验就会失败。我见过很多“莫名奇妙认证失败”最后查下来就是节点时间差了半分钟。
• 检查MySQL服务、消息队列服务是否正常。keystone本身不直接用RabbitMQ，但后续组件会依赖，这里不展开。

2.2 创建keystone数据库和账号

keystone的元数据（用户、项目、角色、服务、endpoint等）默认存储在数据库中。先进入MySQL命令行，执行：

CREATE DATABASE keystone; GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' IDENTIFIED BY 'KEYSTONE_DBPASS'; GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' IDENTIFIED BY 'KEYSTONE_DBPASS'; FLUSH PRIVILEGES;

这里有两个细节值得说。第一，数据库名就叫keystone，不要自定义，后面配置文件和初始化脚本都会按这个默认值来找。第二，授权最好同时给localhost和%。实际运行中，keystone进程在控制节点本地通过socket或localhost连接数据库，但如果后续你迁移服务或使用VIP，不带%授权会导致远端连接直接被拒绝。密码KEYSTONE_DBPASS要选择一个强度足够的串，并且记录下来，后面配置文件会用到。

创建完成后，可以先验证一下：

mysql -u keystone -pKEYSTONE_DBPASS -h controller -e "USE keystone; SHOW TABLES;"

这时候应该能连上，但表还为空，不用担忧。如果不小心把密码写进命令行，shell历史会留下痕迹，测试完建议清理一下。

2.3 安装和启动memcached

Queens版本的keystone有两种常见缓存选择：一种是直接把cache后端配成内存（不推荐，多进程下要加锁），另一种是使用memcached。我建议控制节点上把memcached装好并配置到keystone里，这样token校验、目录获取这些高频操作都能走缓存，压力小很多。执行：

yum install -y memcached systemctl enable --now memcached ss -lntp | grep 11211

看到11211端口监听就说明memcached起来了。默认配置监听本机，这就可以了。keystone在控制节点本地访问它，没必要把memcached暴露到外部网络，对外开放反而增加安全风险。

2.4 安装keystone、Apache和相关依赖

然后是装软件包。注意，这里不只是装openstack-keystone，还要装httpd和mod_wsgi，因为Queens版本不再推荐用独立的keystone-all或eventlet方式启动服务，而是以WSGI应用跑在Apache里。同时装python-openstackclient，因为后续所有验证命令都靠它。

yum install -y openstack-keystone httpd mod_wsgi python-openstackclient

装完可以先看下版本，确保是从Queens源里拉出来的：

rpm -qa | grep openstack-keystone

如果之前装过旧版本的keystone，或者系统自带了一个老版本httpd，建议先卸载干净再装，避免出现WSGI脚本路径不匹配之类的诡异问题。安装完成后，默认会有一个/etc/keystone/目录，里面放着keystone.conf配置文件；还有一个/etc/httpd/conf.d/目录，一会我们要在那边新建WSGI虚拟主机配置。

3. 安装配置核心步骤：从keystone.conf到bootstrap

3.1 修改keystone.conf里的关键参数

keystone的主要配置都在/etc/keystone/keystone.conf。这个文件很大，很多默认项不需要动。如果需要修改，我习惯用crudini命令，比如：

crudini --set /etc/keystone/keystone.conf database connection mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone crudini --set /etc/keystone/keystone.conf token provider fernet crudini --set /etc/keystone/keystone.conf cache enabled True crudini --set /etc/keystone/keystone.conf cache backend dogpile.cache.backends.memcached crudini --set /etc/keystone/keystone.conf cache memcache_servers controller:11211

对应的原生配置文件里，关键片段是这样的：

[database] connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone [token] provider = fernet [cache] enabled = True backend = dogpile.cache.backends.memcached memcache_servers = controller:11211

重点解释一下为什么这么配。数据库连接串用的是mysql+pymysql，这是Python连接MySQL的驱动，Queens官方文档推荐用PyMySQL来避免老式MySQLdb在Python 3环境下的兼容性问题。controller这个主机名必须能被控制节点自己解析，否则连接会卡在DNS解析上。

[token] provider = fernet是Queens默认也在用的配置，显式写出来是为了告诉后期维护的人，我们没有使用其他token机制。[cache]这一段的意义在于把keystone的token和catalog数据缓存到memcached，可以显著降低数据库压力。如果只想先跑通，不配[cache]也可以，但实际生产环境建议配上，毕竟多节点高并发时这里会是第一个瓶颈。

配置完以后，检查一下配置文件权限，确保/etc/keystone/keystone.conf、/etc/keystone/fernet-keys/这些路径不能被普通用户修改。默认是keystone用户所有，保持默认即可。

3.2 同步数据库并生成Fernet密钥

配置改完后，先同步数据库结构。同步动作必须用keystone用户身份执行，否则创建出来的表可能属于root，后续keystone进程因权限不足读不了这些表。

su -s /bin/sh -c "keystone-manage db_sync" keystone

这个命令会把keystone需要的所有表建出来，包括user、project、role、service、endpoint等。执行完没有任何报错，再进MySQL确认一下：

USE keystone; SHOW TABLES;

应该能看到一堆表，大致数一下至少在十张以上。如果表数量异常，优先查数据库连接串和授权。

然后是初始化Fernet密钥目录：

keystone-manage fernet_setup --keystone-user keystone --keystone-group keystone

这条命令会在/etc/keystone/fernet-keys/下生成密钥文件。默认会生成两个比较重要的文件，一个用于当前token签名，另一个用于密钥轮换过渡期。还要确认目录的属主是keystone：

ls -l /etc/keystone/fernet-keys/

看到文件所有者和组都是keystone才正常。如果属主不对，后面Apache以keystone用户运行时会读不到密钥，token签发和校验都会失败。这个权限问题非常典型，尤其很多教程里直接以root执行了ferneta_setup，结果文件属于root。

3.3 用bootstrap完成初始化

现在是最关键的一步。以前需要手动画一堆初始化数据的操作，现在一行keystone-manage bootstrap就能完成。它的作用是创建默认域、admin用户、admin项目、admin角色，并且把admin用户和admin角色绑定到admin项目上。同时，它还顺带把admin用户的三个endpoint写进服务目录，减少后续手工操作。

执行命令是：

keystone-manage bootstrap \ --bootstrap-password ADMIN_PASS \ --bootstrap-admin-url http://controller:5000/v3/ \ --bootstrap-internal-url http://controller:5000/v3/ \ --bootstrap-public-url http://controller:5000/v3/ \ --bootstrap-region-id RegionOne

这里要特别强调两点。第一，ADMIN_PASS一定要用一个你自己记得住、并且后续会写进admin-openrc.sh的密码。第二，三个URL都指向http://controller:5000/v3/，这是Queens版本的标准做法，老教程里admin接口用35357端口的写法在Queens已经不再适用了。RegionOne是我们约定的region名字，后面创建其他服务的endpoint都要保持一致。

这个命令是幂等性比较好的，但如果执行时提示“已经存在”，多半是之前手动创建过admin相关实体，这时候建议直接清空keystone数据库重建，不要试图手动去改。bootstrap没有输出大量信息，只要没有ERROR，基本就是成功了。

3.4 配置Apache以WSGI方式提供keystone服务

keystone的API最终要暴露在网络端口上。Queens官方文档里给出的是两个VirtualHost，分别挂载keystone-wsgi-public和keystone-wsgi-admin脚本，但我在实际部署中发现，如果两个VirtualHost都监听5000端口，Apache只会把请求交给默认的第一个VirtualHost，第二个脚本基本不会被使用。与其留着一个可能引起困惑的配置，不如就写一个VirtualHost，统一挂载public脚本，效果完全一致。

创建/etc/httpd/conf.d/wsgi-keystone.conf，内容如下：

Listen 5000 <VirtualHost *:5000> WSGIDaemonProcess keystone processes=5 threads=1 display-name=keystone WSGIProcessGroup keystone WSGIScriptAlias / /usr/bin/keystone-wsgi-public WSGIApplicationGroup %{GLOBAL} WSGIPassAuthorization On ErrorLog /var/log/httpd/keystone.log CustomLog /var/log/httpd/keystone_access.log combined <Directory /usr/bin> Require all granted </Directory> </VirtualHost>

WSGIPassAuthorization On这一行极其重要。Apache默认会把请求头里的Authorization信息吞掉，如果不打开这个开关，keystone收到的是空的认证头，所有带token的请求都会变成401。processes=5 threads=1可以按控制节点CPU核数调整，测试环境不用太纠结这个数字。

配置完成后：

systemctl enable --now httpd systemctl status httpd ss -lntp | grep 5000

如果看到5000端口已经监听，curl一下：

curl -s http://controller:5000/v3 | python -m json.tool

正常情况下会返回一个包含version信息的JSON。如果这一步报错，去/var/log/httpd/keystone.log看具体原因，最常见的还是SELinux问题。

3.5 在keystone里创建service项目、服务实体和endpoint

bootstrap只是把admin的基础数据建好了，真正的OpenStack服务还没有注册。每一个需要接入keystone的服务，都应该在一个叫service的项目下创建自己的用户，然后向keystone注册服务类型和endpoint。所以这一步先创建service项目：

先设置环境变量，让openstack命令知道怎么访问keystone：

export OS_USERNAME=admin export OS_PASSWORD=ADMIN_PASS export OS_PROJECT_NAME=admin export OS_USER_DOMAIN_NAME=Default export OS_PROJECT_DOMAIN_NAME=Default export OS_AUTH_URL=http://controller:5000/v3 export OS_IDENTITY_API_VERSION=3

这里的变量一个都不能少，特别是两个domain相关变量。如果不带，openstack客户端会默认用Default域，问题是环境变量缺失时有些版本会直接报“Forbidden”或“Could not determine project domain”，让人误以为密码错了。

然后执行：

openstack project create --domain default --description "Service Project" service openstack service create --name keystone --description "OpenStack Identity" identity openstack endpoint create --region RegionOne identity public http://controller:5000/v3/ openstack endpoint create --region RegionOne identity internal http://controller:5000/v3/ openstack endpoint create --region RegionOne identity admin http://controller:5000/v3/

注意，openstack service create里的identity是服务类型type，keystone是服务名称name。后面_create endpoint_时要按服务类型identity来关联，而不是按服务名称keystone。很多第一次碰openstack命令的人在这里会写错，结果创建endpoint时报“service not found”。

三个endpoint地址可以完全一样，都是http://controller:5000/v3/，但是类型不同。public是客户端访问用的，internal是服务间调用用的，admin是管理操作用的。在Keystone v3里三个接口统一走5000端口，所以可以填一样的地址；如果网络规划里需要区分管理网和业务网，再把internal/admin换成对应内部地址就行。

3.6 顺手建一个普通项目和普通用户

如果只是把keystone跑起来，上面已经够了。但为了验证后续普通用户能不能正常使用，建议顺手创建一个测试项目和一个测试用户：

openstack project create --domain default --description "My Project" myproject openstack user create --domain default --password myuserpass myuser openstack role add --project myproject --user myuser member

这样后面装完其他服务，用myuser/myuserpass登录也可以看到云平台里属于自己项目的资源。这一步能提前暴露“用户创建成功但登录后看不到项目”的问题。创建用户时如果没有指定domain，OpenStack默认也会放进Default域，但显式写清楚更安全。

4. 验证keystone安装结果：用命令行证明它能干活

4.1 写一个admin环境变量脚本

手动export环境变量只适合当场用，一旦开了新终端就要重敲一遍。正确的做法是写一个admin-openrc.sh脚本，后面每次要用管理员操作时source一下：

cat > ~/admin-openrc.sh <<'EOF' export OS_PROJECT_DOMAIN_NAME=Default export OS_USER_DOMAIN_NAME=Default export OS_PROJECT_NAME=admin export OS_USERNAME=admin export OS_PASSWORD=ADMIN_PASS export OS_AUTH_URL=http://controller:5000/v3 export OS_IDENTITY_API_VERSION=3 export OS_IMAGE_API_VERSION=2 EOF chmod 600 ~/admin-openrc.sh source ~/admin-openrc.sh

注意OS_PROJECT_DOMAIN_NAME和OS_USER_DOMAIN_NAME都要设成Default，这两个变量决定了用户和项目从哪个域里检索。如果只想试一次，可以写unset OS_AUTH_TYPE，但没必要深究，直接套用上面的模板就好。

4.2 核心验证命令

执行以下几组命令，全部成功才算keystone真正可用。

openstack token issue openstack project list openstack user list openstack role list openstack service list openstack endpoint list

openstack token issue会返回一个token id、过期时间等信息，如果执行成功，说明密码、项目、域、认证URL全都没问题。这个命令基本就是keystone部署最直接的“体检报告”。后面的list命令分别查看项目、用户、角色、服务和endpoint是否都已经正确入库。如果某个list返回为空，回到上一章确认是否漏建了对应实体。例如openstack service list至少能看到里面有一行identity类型的keystone服务；openstack endpoint list能看到三个地址相同的endpoint。

再验证一下普通用户：

source ~/admin-openrc.sh openstack user show myuser openstack project show myproject

这些命令不会修改数据，可以反复执行，用来排查数据是否齐全。

4.3 验证失败时的快捷定位

如果openstack token issue报错，不要急着改配置，先按下面顺序检查：

• OS_AUTH_URL是不是http://controller:5000/v3，注意controller这个主机名在客户端机器上也要能解析。
• 密码和OS_USERNAME是否匹配。
• 有没有漏掉OS_USER_DOMAIN_NAME或OS_PROJECT_DOMAIN_NAME。
• 控制节点时间是否准确。
• /var/log/keystone/keystone.log或/var/log/httpd/keystone.log里有没有异常。

我在实战中遇到过最多的问题反而是环境变量残留。比如之前用一台机器访问过别的OpenStack环境，过了很久又回到新环境，shell里还留着旧的OS_PROJECT_NAME或OS_AUTH_URL。遇到莫名其妙的认证错误，第一时间env | grep OS_看看变量是什么，再决定要不要重设。

5. 实战中的坑和排查：都是花钱买得到的教训

5.1 数据库连接错误

错误表现：执行keystone-manage db_sync时报pymysql.err.OperationalError: (1045, "Access denied for user 'keystone'@'controller'...)。

排查方式：先确认MySQL里是否有对应账号，是否授权了keystone库，密码是否和配置串里一致。尤其注意，MySQL的user表里host字段如果只授权了localhost，从controller主机连接时会被拒绝，需要补上%授权。还有如果密码里有特殊字符，比如@、#，写在连接串里可能会被截断，这时候要么换一个不含特殊字符的密码，要么在连接串里做URL编码。我建议测试环境密码保持简单字母数字组合，避免这类低级问题。

5.2 Apache启动后访问5000端口报500

错误表现：curlhttp://controller:5000/v3返回500，日志/var/log/httpd/keystone.log里报Permission denied。

大概率是SELinux拦截了httpd对外连接keystone的socket，或者拦截了它执行/usr/bin/keystone-wsgi-public脚本。有两个处理思路。

如果决定保留SELinux，就让httpd放行网络连接：

setsebool -P httpd_can_network_connect on

如果还报脚本权限问题，再把keystone的wsgi脚本上下文修正为httpd可执行：

semanage fcontext -a -t httpd_sys_script_exec_t "/usr/bin/keystone-wsgi-public" restorecon -v /usr/bin/keystone-wsgi-public

如果不想折腾，直接在/etc/selinux/config里把SELinux设为disabled并重启，自己搭建的测试环境无伤大雅。但生产环境还是建议正确设置布尔规则。

5.3 bootstrap执行成功但admin密码不生效

错误表现：openstack token issue用admin密码登录总是报401。

常见原因有两个。第一，bootstrap执行前数据库里已经有旧的admin数据和密码，bootstrap可能不会覆盖掉已经存在的实体密码。解决办法是drop掉keystone数据库重建，然后重新执行keystone-manage db_sync和bootstrap，确保从干净状态开始。第二，执行bootstrap时--bootstrap-password参数里如果包含空格或特殊字符，命令行解析可能出错，这种情况下建议密码改简单再试。

5.4 所有组件都能连keystone，但token校验失败

错误表现：后续组件调用keystone时反复报token无效，或者401。

先看时间同步。NTP偏差超过允许范围，token的issued_at和expires_at就会被判定异常。在控制节点执行date，再和另一台节点对比，如果偏差明显，重新配置chrony并重启服务。再看Fernet密钥。如果控制节点有多个，要确保/etc/keystone/fernet-keys/下的文件完全一致，不然A节点签发的token拿到B节点去验证，由于密钥不同直接失败。单节点环境一般不会出现这个问题，但也会出现密钥文件权限被改坏、keystone进程读不到的情况，检查ls -l /etc/keystone/fernet-keys/即可。

5.5 endpoint创建报“service with name xxx not found”

错误表现：openstack endpoint create时提示Service with name "keystone" not found。

原因基本是在openstack service create时使用的服务类型和endpoint create时使用的type不一致。比如创建service时写的是--type keystone，而endpoint里第三段参数也写成了identity，两个不一致就会查不到。解决方法是重新创建正确的service实体，或者先openstack service list确认现有的type名称，endpoint命令按它来写。

5.6 常见问题速查表

6. keystone装完还要做什么：给后续组件铺路

6.1 建立统一的service项目账号规范

后续安装glance、nova、neutron时，都需要先到keystone里创建对应的用户。主流做法是把这些组件用户都放在service项目下，统一赋予admin角色：

openstack project create --domain default --description "Service Project" service # 如果前面没建 openstack user create --domain default --password glance_pass glance openstack role add --project service --user glance admin

用这种方式，后续每个组件在配置自己的服务认证时，用户名就是组件名，项目固定是service，角色固定是admin，规则统一，复杂度最低。不建议给每个组件单独建项目，那样管理起来会非常散乱。

6.2 Fernet密钥的备份和轮换要考虑

Fernet密钥不是一次生成就永远不动。OpenStack官方推荐在密钥轮换窗口内执行keystone-manage fernet_rotate，把旧的当前密钥变成主密钥，并生成一个新的当前密钥。单控制节点测试环境可以不做轮换，但要注意备份/etc/keystone/fernet-keys/整个目录。一旦密钥丢失，所有现网用户的token都会失效，等于要让全员重新登录。多控制节点场景，需要把该目录同步到所有控制节点，且保持属主和权限一致。

6.3 下一步可以往glance和nova走了

keystone跑通以后，下一个通常是镜像服务glance。装glance时会继续用到openstack service create --name glance --type image和openstack endpoint create，正好把刚才服务目录的用法再巩固一遍。之后的nova更复杂一些，它不仅要注册服务，还要配置Placement相关的服务账号。这些组件在安装时，几乎都要回来查询keystone的endpoint，所以只要keystone这关稳了，后面就是按模板重复“建用户、注册服务、创建endpoint、改配置文件”的流程。

我个人在实际操作中的体会是，keystone的坑大多不是keystone本身，而是环境因素：数据库权限、SELinux、时间同步、环境变量残留。装之前把这几项确认好，后面基本是一路顺畅。如果你搭建过程中遇到了报错，先别急着上网搜，打开日志看两分钟往往比搜半小时更有效。最后再分享一个小习惯：每完成一个组件的安装，立刻用openstack token issue验证一次，如果这个命令都过不去，就不要继续往下装，先回来把keystone调好再走。